{
  "schema_version": 2,
  "id": "integrate/sidekiq",
  "title": "Redis with Sidekiq",
  "url": "https://redis.io/docs/latest/integrate/sidekiq/",
  "summary": "Run Ruby background jobs with Sidekiq and Redis.",
  "tags": [
    "docs",
    "integrate",
    "oss",
    "rs",
    "rc"
  ],
  "last_updated": "2026-11-17T15:15:32Z",
  "children": [],
  "page_type": "content",
  "content_hash": "e9a1f9611bcaf91882a98187c47f6ea7cf4494e9612c38558ed663b09cd69da5",
  "sections": [
    {
      "id": "overview",
      "title": "Overview",
      "role": "overview",
      "text": "[Sidekiq](https://sidekiq.org/) runs background jobs in Ruby, using threads to process\nmany jobs at once. Redis is Sidekiq's only data store: queues, schedules, retries, and\nstatistics all live there. See the\n[job queue use case](https://redis.io/docs/latest/develop/use-cases/job-queue) for when to\nchoose this pattern."
    },
    {
      "id": "requirements",
      "title": "Requirements",
      "role": "content",
      "text": "| Dependency | Supported versions |\n|------------|--------------------|\n| Sidekiq | 8.x (the examples were run with 8.1.7) |\n| Redis | 7.0 or later (Sidekiq checks this at startup and refuses to run on an older server) |\n| Ruby | 3.2 or later (the examples were run with Ruby 4.0.6) |\n\nInstall the gem:\n\n[code example]\n\nYou also need a running Redis server. You can run one locally with\n[Redis Open Source](https://redis.io/docs/latest/operate/oss_and_stack/install/archive/install-redis),\nuse [Docker](https://hub.docker.com/_/redis), or connect to\n[Redis Cloud](https://redis.io/cloud/)."
    },
    {
      "id": "define-a-job",
      "title": "Define a job",
      "role": "content",
      "text": "Include `Sidekiq::Job` in a class and write a `perform` method. Point both the server\n(worker) and the client (the code that enqueues jobs) at your Redis server:\n\n[code example]\n\nArguments must be simple JSON types, because Sidekiq stores the job as JSON in Redis."
    },
    {
      "id": "enqueue-and-run-jobs",
      "title": "Enqueue and run jobs",
      "role": "content",
      "text": "Call `perform_async` to run a job as soon as a worker is free, and `perform_in` to run it\nlater:\n\n[code example]\n\nStart the worker process in a separate terminal. The `-r` option loads the file that\ndefines your jobs, and `-c` sets the number of threads:\n\n[code example]\n\n> [!NOTE]\n> Sidekiq checks for scheduled jobs with a poller that runs about every 5 seconds on average.\n> On a freshly started worker, a job scheduled 2 seconds ahead ran 8 to 10 seconds after it was\n> enqueued. Don't rely on `perform_in` for sub-second or few-second accuracy."
    },
    {
      "id": "what-sidekiq-stores-in-redis",
      "title": "What Sidekiq stores in Redis",
      "role": "content",
      "text": "| Key | Type | Contents |\n|-----|------|----------|\n| `queue:<name>` | list | Jobs waiting to run, as JSON. |\n| `schedule` | sorted set | Jobs scheduled with `perform_in`, scored by run time. |\n| `retry` | sorted set | Jobs that failed and will be retried, scored by the next attempt time. |\n| `dead` | sorted set | Jobs that failed all their retries. |\n| `queues` and `processes` | set | The queue names and the running worker processes. |\n\nA job that raises an error moves to the `retry` set with a `retry_count` and the error\nmessage. In the examples, a job that always raises `smtp down` appeared in the retry set\nafter its first failure, with `retry_count` 0 and the next attempt about 11 seconds\naway. Use `Sidekiq::RetrySet` and the other classes in `sidekiq/api` to inspect these sets\nfrom Ruby."
    },
    {
      "id": "what-happens-to-a-job-when-a-worker-stops",
      "title": "What happens to a job when a worker stops",
      "role": "content",
      "text": "Sidekiq removes a job from its queue with [`BRPOP`](https://redis.io/docs/latest/commands/brpop) when a\nworker takes it. The job then exists only in the worker's memory, so the result depends on\nhow the worker stops:\n\n- **Graceful shutdown** (`TERM`): Sidekiq waits for running jobs up to the shutdown timeout\n  (`-t`), then pushes any that are still running back to Redis. With `-t 2` and a 30-second\n  job, the log shows `Pushed 1 jobs back to Redis`, and the job is back in `queue:default`.\n- **Hard kill** (`kill -9`, or a crash): the running job is gone. After a `kill -9` of a worker\n  that was running a 30-second job, the queue, `retry`, and `dead` were all empty.\n\nWrite jobs so that running one twice is safe, and give your process manager a stop timeout\nlonger than your Sidekiq shutdown timeout."
    },
    {
      "id": "more-information",
      "title": "More information",
      "role": "content",
      "text": "- [Sidekiq documentation](https://github.com/sidekiq/sidekiq/wiki)\n- [Sidekiq on GitHub](https://github.com/sidekiq/sidekiq)"
    }
  ],
  "examples": [
    {
      "id": "requirements-ex0",
      "language": "bash",
      "code": "bundle add sidekiq",
      "section_id": "requirements"
    },
    {
      "id": "define-a-job-ex0",
      "language": "ruby",
      "code": "require \"sidekiq\"\n\nSidekiq.configure_server { |config| config.redis = { url: \"redis://<your-redis-host>:6379/0\" } }\nSidekiq.configure_client { |config| config.redis = { url: \"redis://<your-redis-host>:6379/0\" } }\n\nclass WelcomeEmailJob\n  include Sidekiq::Job\n  sidekiq_options queue: \"default\", retry: 3\n\n  def perform(user_id, greeting)\n    puts \"Sending welcome to #{user_id}: #{greeting}\"\n  end\nend",
      "section_id": "define-a-job"
    },
    {
      "id": "enqueue-and-run-jobs-ex0",
      "language": "ruby",
      "code": "WelcomeEmailJob.perform_async(42, \"hello\")\nWelcomeEmailJob.perform_in(60, 43, \"a minute later\")",
      "section_id": "enqueue-and-run-jobs"
    },
    {
      "id": "enqueue-and-run-jobs-ex1",
      "language": "bash",
      "code": "bundle exec sidekiq -r ./worker.rb -c 3",
      "section_id": "enqueue-and-run-jobs"
    }
  ]
}
