LavinMQ is a high-performance message queue & streaming server implementing the AMQP 0-9-1 and MQTT 3.1.1 protocols. Built with Crystal for optimal efficiency.

• Lightning Fast: Exceptional throughput performance
• Resource Efficient: Minimal RAM requirements
• Highly Scalable: Handles very long queues and numerous connections
• Simple Setup: Requires minimal configuration to get started

Discover more at LavinMQ.com

Installation

See Installation guide for more information on installing LavinMQ.

Debian/Ubuntu

curl -fsSL https://packagecloud.io/cloudamqp/lavinmq/gpgkey | gpg --dearmor | sudo tee /usr/share/keyrings/lavinmq.gpg > /dev/null
. /etc/os-release
echo "deb [signed-by=/usr/share/keyrings/lavinmq.gpg] https://packagecloud.io/cloudamqp/lavinmq/$ID $VERSION_CODENAME main" | sudo tee /etc/apt/sources.list.d/lavinmq.list
sudo apt-get update
sudo apt-get install lavinmq

Fedora

sudo tee /etc/yum.repos.d/lavinmq.repo << 'EOF'
[lavinmq]
name=LavinMQ
baseurl=https://packagecloud.io/cloudamqp/lavinmq/fedora/$releasever/$basearch
gpgkey=https://packagecloud.io/cloudamqp/lavinmq/gpgkey
repo_gpgcheck=1
gpgcheck=0
EOF
sudo dnf install lavinmq

macOS

Install LavinMQ with brew:

brew install cloudamqp/cloudamqp/lavinmq

Docker

Docker images are published to Docker Hub. Fetch and run the latest version with:

docker run --rm -it -p 5672:5672 -p 15672:15672 -v /tmp/amqp:/var/lib/lavinmq cloudamqp/lavinmq

Docker Compose

Minimal example on how to run LavinMQ with Docker compose.

services:
  lavinmq:
    image: "cloudamqp/lavinmq:latest"
    ports:
      - 15672:15672 # HTTP
      - 5672:5672   # AMQP

Start the container by running docker compose up

From Source

Begin with installing Crystal. Refer to Crystal's installation documentation on how to install Crystal.

Clone the git repository and build the project.

git clone [email protected]:cloudamqp/lavinmq.git
cd lavinmq
make
sudo make install # optional

Using LavinMQ

Getting Started

For a quick start guide on using LavinMQ, see the getting started documentation.

Running LavinMQ

LavinMQ only requires one argument: a path to a data directory.

lavinmq -D /var/lib/lavinmq

More configuration options can be viewed with -h, and you can specify a configuration file too, see extras/lavinmq.ini for an example, or see the section on config files in the documentation.

Client Libraries

All AMQP client libraries work with LavinMQ, and there are AMQP client libraries for almost every platform. The LavinMQ website has guides for many common platforms:

• Ruby
• Node.js
• Java
• Python
• PHP
• Crystal
• Go
• .NET

Performance

A single c8g.large EC2 instance with a GP3 EBS drive (XFS formatted) can sustain about 820,000 messages/s (16 byte message body, single queue, single producer, single consumer). A single producer can push 1,600,000 msgs/s and if there are no producers, auto-ack consumers can receive 1,200,000 msgs/s.

Enqueueing 100M messages only uses 25 MB RAM. 8,000 connections use only about 400 MB RAM. Declaring 100,000 queues uses about 100 MB RAM. About 1,600 bindings per second can be made to non-durable queues, and about 1,000 bindings/second to durable queues.

You can use lavinnmqperf to verify these results for yourself.

Features

Core Protocols

• AMQP 0-9-1 protocol support
• MQTT 3.1.1 protocol support
• AMQPS (TLS)
• AMQP over websockets
• MQTT over websockets

Messaging Capabilities

• Publisher confirm
• Transactions
• Dead-lettering
• TTL support on queue, message, and policy level
• CC/BCC
• Alternative exchange
• Exchange to exchange bindings
• Direct-reply-to RPC
• Queue max-length
• Priority queues
• Delayed exchanges
• Message deduplication

Management

• HTTP API
• Users and ACL rules
• VHost separation
• Policies
• Importing/export definitions
• Consumer cancellation

High Availability

• Replication
• Automatic leader election in clusters via etcd

Other Functionality

• Shovels
• Queue & Exchange federation
• Single active consumer
• Stream queues

Feature Highlights

Clustering

LavinMQ can be fully clustered with multiple other LavinMQ nodes. One node is always the leader and the others stream all changes in real-time. Failover happens instantly when the leader is unavailable.

etcd is used for leader election and maintaining the In-Sync-Replica (ISR) set. LavinMQ then uses a custom replication protocol between the nodes. When a follower disconnects it will fall out of the ISR set, and will then not be eligible to be a new leader.

See Setting up Clustering with LavinMQ for more information on Clustering in LavinMQ.

Clustering Configuration

Enable clustering with the following config:

[clustering]
enabled = true
bind = ::
port = 5679
advertised_uri = tcp://my-ip:5679
etcd_endpoints = localhost:2379

or start LavinMQ with:

lavinmq --data-dir /var/lib/lavinmq --clustering --clustering-bind :: --clustering-advertised-uri=tcp://my-ip:5679

Stream Queues

Stream queues provide an append-only log structure that allows multiple consumers to read the same messages independently. Unlike standard queues, messages in stream queues aren't deleted when consumed, making them ideal for event sourcing patterns and multi-consumer scenarios.

Each consumer can start reading from anywhere in the queue using the x-stream-offset consumer argument and can process messages at their own pace. See Stream Queues in the documentation for more information on using Stream Queues.

Stream Queue Filtering

Stream queues support message filtering, allowing consumers to receive only messages that match specific criteria. This is useful for consuming a subset of messages without creating multiple queues. For more information on filtering, see the documentation.

MQTT Support

LavinMQ natively supports the MQTT 3.1.1 protocol, facilitating seamless integration with IoT devices, sensors, and mobile applications. Each MQTT session is backed by an AMQP queue, ensuring consistent and reliable message storage. Messages within these sessions are persistently stored on disk.

For retained messages, LavinMQ maintains a dedicated storage system that maps topics to their respective retained messages. These retained messages are also persistently stored, ensuring that new subscribers immediately receive the latest retained message upon subscribing, including those using wildcard topic filters. In a clustered environments, the retained message store is replicated across nodes.

Please note that Quality of Service (QoS) level 2 is not supported in LavinMQ; messages published with QoS 2 will be downgraded to QoS 1.

See MQTT in LavinMQ for more information on using MQTT.

MQTT Configuration

[MQTT]
bind = "127.0.0.1"
port = 1883
tls_port = 8883
unix_path = ""
max_inflight_messages = 65535
default_vhost = "/"

Implementation Details

LavinMQ is built in Crystal and uses a disk-first approach to message storage, letting the OS handle caching. For full details on implementation, storage architecture, and message flows, see the Implementation details section in CONTRIBUTING.md.

Compatibility Notes

There are a few edge-cases that are handled a bit differently in LavinMQ compared to other AMQP servers:

• When comparing queue/exchange/binding arguments all number types (e.g. 10 and 10.0) are considered equivalent
• When comparing queue/exchange/binding arguments non-effective parameters are also considered, and not ignored
• TTL of queues and messages are accurate to 0.1 second, not to the millisecond
• Newlines are not removed from Queue or Exchange names, they are forbidden

Getting Help

For questions or suggestions:

• Join our Slack community
• Use the lavinmq tag on Stack Overflow
• If you use LavinMQ via CloudAMQP, contact [email protected]
• Want to learn more? Talk with our product experts

Contributing

Please read our contributing guide if you'd like to help improve LavinMQ.

License

The software is licensed under the Apache License 2.0.

Copyright 2018-2025 84codes AB

LavinMQ is a trademark of 84codes AB