Skip to main content

​
Add to Dependencies

Add bullmq to your list of dependencies in mix.exs: 
def deps do
  [
    {:bullmq, "~> 1.2"}
  ]
end
Then run: 
mix deps.get

​
Requirements

  • Elixir: 1.15 or higher
  • Erlang/OTP: 26 or higher
  • Redis: 6.0 or higher (7.0+ recommended for best performance)

​
Dependencies

BullMQ for Elixir includes the following dependencies:
  • redix (~> 1.3) - Redis client
  • nimble_pool (~> 1.0) - Connection pooling
  • nimble_options (~> 1.0) - Configuration validation
  • jason (~> 1.4) - JSON encoding/decoding
  • crontab (~> 1.1) - Cron expression parsing
  • msgpax (~> 2.4) - MessagePack encoding for Lua scripts
  • elixir_uuid (~> 1.2) - UUID generation
  • telemetry (~> 1.2) - Instrumentation and monitoring

​
Redis Setup

BullMQ requires a Redis server. You can:

​
Run Redis Locally

# Using Docker
docker run -d -p 6379:6379 redis:latest

# Or install Redis directly
# On Ubuntu/Debian:
sudo apt-get install redis-server

# On macOS:
brew install redis

​
Use a Managed Redis Service

For production, consider using a managed Redis service:

​
Add Redis Connection to Supervision Tree

Add a Redix connection to your application’s supervision tree: 
defmodule MyApp.Application do
  use Application

  def start(_type, _args) do
    children = [
      # Start Redis connection
      {Redix, name: :my_redis, host: "localhost", port: 6379},
      
      # Your other supervised processes...
    ]

    opts = [strategy: :one_for_one, name: MyApp.Supervisor]
    Supervisor.start_link(children, opts)
  end
end

​
Configuration

You can configure your Redis connection in config/config.exs: 
config :my_app, :redis,
  host: "localhost",
  port: 6379,
  password: nil,
  database: 0
Then in your application: 
redis_opts = Application.get_env(:my_app, :redis)
{Redix, Keyword.put(redis_opts, :name, :my_redis)}

​
Verify Installation

You can verify the installation by running: 
mix deps
You should see bullmq in the list of dependencies.

​
Test Redis Connection

Create a simple test to verify your Redis connection: 
# In iex -S mix
{:ok, conn} = Redix.start_link(host: "localhost", port: 6379)
Redix.command(conn, ["PING"])
# Should return {:ok, "PONG"}

​
Common Issues

​
Redis Connection Errors

If you can’t connect to Redis:
  1. Verify Redis is running: redis-cli ping (should return PONG)
  2. Check your host and port configuration
  3. Ensure your firewall allows connections to the Redis port (default: 6379)
  4. If using Redis Cloud or other managed services, verify credentials

​
Compilation Errors

If you encounter compilation errors:
  1. Ensure you’re running Elixir 1.15+ and Erlang/OTP 26+
  2. Run mix deps.clean --all && mix deps.get
  3. Try mix clean && mix compile

​
Optional: Telemetry Setup

For monitoring and observability, you can set up Telemetry handlers: 
defmodule MyApp.Telemetry do
  require Logger

  def attach_handlers do
    :telemetry.attach_many(
      "bullmq-telemetry",
      [
        [:bullmq, :job, :start],
        [:bullmq, :job, :stop],
        [:bullmq, :job, :exception]
      ],
      &handle_event/4,
      nil
    )
  end

  def handle_event([:bullmq, :job, :start], measurements, metadata, _config) do
    Logger.info("Job started: #{metadata.job_id}")
  end

  def handle_event([:bullmq, :job, :stop], measurements, metadata, _config) do
    Logger.info("Job completed: #{metadata.job_id} in #{measurements.duration}ms")
  end

  def handle_event([:bullmq, :job, :exception], measurements, metadata, _config) do
    Logger.error("Job failed: #{metadata.job_id} - #{metadata.reason}")
  end
end
Call this in your application start: 
def start(_type, _args) do
  MyApp.Telemetry.attach_handlers()
  # ...
end

​
Next Steps

Usage Guide

Learn how to create queues and workers

Build docs developers (and LLMs) love

Get started for freeTalk to us