Skip to content
EventMachine-based RabbitMQ client. Prefer Bunny: See documentation guides at
Ruby Shell
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Failed to load latest commit information.


About amqp gem

amqp gem is a widely used, feature-rich, well-maintained asynchronous AMQP 0.9.1 client with batteries included.
This library works with Ruby 1.8.7, Ruby 1.9.2, JRuby, REE and Rubinius, and is
licensed under the Ruby License.
Versions 0.8.0 and later of amqp gem implement AMQP 0.9.1.

I know what AMQP is, how do I get started?

See “Getting started with amqp gem” and “Documentation: tutorials, guides & API reference” sections below.

What is AMQP?

AMQP is an open standard for messaging middleware that
emphasizes interoperability between different technologies (for example, Java, .NET,
Ruby, Python, C and so on).

Key features of AMQP are very flexible yet simple routing and binary protocol

What is amqp gem good for?

One can use amqp gem to make Ruby applications interoperate with other
applications (both Ruby and not). Complexity and size may vary from
simple work queues to complex multi-stage data processing workflows that involve
dozens or hundreds of applications built with all kinds of technologies.

Specific examples:

  • A Web application may route messages to a Java app that works
    with SMS delivery gateways.
  • Periodically run (Cron-driven) application may notify other systems that
    there are some new results.
  • Content aggregators may update full-text search and geospatial search indexes
    by delegating actual indexing work to other applications over AMQP.
  • Companies may provide “Firehose-like” push APIs to their customers, partners
    or just general public.
  • A new shiny Ruby-based system may be integrated with an existing C++-based component
    using AMQP.
  • An application that watches updates from a real-time stream (be it markets data
    or Twitter stream) can propagate updates to interested parties, including
    Web applications that display that information in the real time.

Getting started with amqp gem

Install RabbitMQ

Please refer to RabbitMQ installation guide
Note that for Ubuntu and Debian we strongly advice that you use RabbitMQ apt repository
that has recent versions of RabbitMQ. Learn more in {file:docs/RabbitMQVersions.textile RabbitMQ versions} section.

Install the gem

gem install amqp

“Hello, World” example

#!/usr/bin/env ruby
# encoding: utf-8

require "rubygems"
# or
# require "bundler"
# Bundler.setup
# if you use Bundler

require 'amqp' do
  connection = AMQP.connect(:host => '')
  puts "Connected to AMQP broker. Running #{AMQP::VERSION} version of the gem..."

  channel  =
  queue    = channel.queue("amqpgem.examples.hello_world", :auto_delete => true)
  exchange ="")

  queue.subscribe do |payload|
    puts "Received a message: #{payload}. Disconnecting..."

    connection.close {
      EM.stop { exit }

  exchange.publish "Hello, world!", :routing_key =>

(see as a Gist)

Documentation: tutorials, guides & API reference

We believe that in order to be the best Ruby AMQP client out there, we need to care about documentation as much as
code readability, API beauty and autotomated testing across 5 Ruby implementations on 3 operating systems.


We have written and maintain Getting started guide that is written in form of a tutorial.
Check it out! If something isn’t clear, every guide explains how to contact documentation authors.


You can find many examples (both real-world cases and simple demonstrations)
under examples directory in the repository.
Note that those examples are written against version 0.8.0.rc1 and later. 0.6.x and 0.7.x
may not support certain AMQP protocol or “DSL syntax” features.


Documentation guides describe
the library itself as well as AMQP usage scenarios, routing, error handing & recovery, broker-specific extensions, TLS support and so on.

API reference

Reference documentation is up on and is updated daily.

If you don’t find your answer in documentation, we consider it a high severity bug that you should file to us.

How to use AMQP gem with Ruby on Rails, Merb, Sinatra and other web frameworks

To use AMQP gem from web applications, you would need to have EventMachine reactor running.
If you use Thin or Goliath,
you are all set: those two servers use EventMachine under the hood.

With other web servers, you need to start EventMachine reactor in a separate thread like this: { }

Otherwise EventMachine will block current thread.

Then connect to AMQP broker:

amqp_connection = AMQP.connect(:host => "localhost", :user => "guest", :pass => "guest", :vhost => "/")

In a Ruby on Rails app, probably the best place for this code is initializer
(like config/initializers/amqp.rb). For Merb apps, it is config/init.rb. For
Sinatra and pure Rack applications, place it next to other configuration

If you want to integrate AMQP with Thin, Goliath or
some other EventMachine-based software which already runs an event loop, you might want to use following code:

EM.next_tick { AMQP.connect(...) }

So in case EventMachine reactor isn’t running yet on server/application boot,
connection won’t fail but instead wait for reactor to start.

Same separate thread technique can be used to make EventMachine play nicely with other
libraries that would block current thread (like File::Tail).

Using amqp gem in your app/library using Bundler

With Bundler, add this line to your Gemfile:

gem "amqp"

If you want to use edge version (usually there is no need to):

gem "amqp", :git => "git://", :branch => "master"

How does amqp gem relate to amq-client gem, amq-protocol and libraries like bunny?

See this page about AMQP gems family

How can I learn more?

AMQP resources

Messaging and distributed systems resources



AMQP gem is licensed under the Ruby License.

Credits and copyright information

  • The Original Code is tmm1/amqp.
  • The Initial Developer of the Original Code is Aman Gupta.
  • Copyright © 2008 – 2010 Aman Gupta.
  • Contributions from Jakub Stastny are Copyright © 2011 VMware, Inc.
  • Copyright © 2010 — 2011 ruby-amqp group members.

Currently maintained by ruby-amqp group members
Special thanks to Dmitriy Samovskiy, Ben Hood and Tony Garnock-Jones.


So, does amqp gem only work with RabbitMQ?

This library was tested primarily with RabbitMQ, although it should be compatible with any
server implementing the AMQP 0.9.1 spec. For AMQP 0.8.0 brokers,
use version 0.7.


Something went wrong with that request. Please try again.