{
  "schema_version": 2,
  "id": "integrate/asynq",
  "title": "Redis with Asynq",
  "url": "https://redis.io/docs/latest/integrate/asynq/",
  "summary": "Run Go background tasks with Asynq and Redis.",
  "tags": [
    "docs",
    "integrate",
    "oss",
    "rs",
    "rc"
  ],
  "last_updated": "2026-11-17T16:15:30Z",
  "children": [],
  "page_type": "content",
  "content_hash": "9ba02358aa1582d7efa02915f2a441742c859f59536bc114aa4b9b6370816e10",
  "sections": [
    {
      "id": "overview",
      "title": "Overview",
      "role": "overview",
      "text": "[Asynq](https://github.com/hibiken/asynq) is a Go library for queueing tasks and\nprocessing them asynchronously with workers. It stores everything in Redis through the\n[go-redis](https://redis.io/docs/latest/develop/clients/go) client. See the [job queue use case](https://redis.io/docs/latest/develop/use-cases/job-queue) for when to choose\nthis pattern."
    },
    {
      "id": "requirements",
      "title": "Requirements",
      "role": "content",
      "text": "The examples on this page were run with Asynq 0.26 and Go 1.27 against Redis 7.2. Add the module to\nyour project:\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": "enqueue-tasks",
      "title": "Enqueue tasks",
      "role": "content",
      "text": "Create a client with your Redis address, build a task with a type name and a payload, and\nenqueue it. Options such as `MaxRetry` and `ProcessIn` control how it runs:\n\n[code example]"
    },
    {
      "id": "process-tasks",
      "title": "Process tasks",
      "role": "content",
      "text": "Create a server, register a handler for each task type on a mux, and run it. A handler that\nreturns an error causes a retry. `asynq.GetRetryCount` tells the handler which attempt this is:\n\n[code example]\n\n> [!NOTE]\n> Asynq moves scheduled and retried tasks to the queue with a poller that runs about every\n> 5 seconds. In a test, a task scheduled 3 seconds ahead ran after 4.8 seconds, and retries\n> with a 1-second delay ran 4.2 to 4.6 seconds apart. Don't rely on `ProcessIn` or on the\n> retry delay for sub-5-second accuracy."
    },
    {
      "id": "what-asynq-stores-in-redis",
      "title": "What Asynq stores in Redis",
      "role": "content",
      "text": "Asynq keys include the queue name in braces:\n\n| Key | Type | Contents |\n|-----|------|----------|\n| `asynq:{default}:pending` | list | Tasks that are ready to run. |\n| `asynq:{default}:scheduled` | sorted set | Tasks enqueued with `ProcessIn`, scored by run time. |\n| `asynq:{default}:retry` | sorted set | Tasks whose handler returned an error and that will be retried. |\n| `asynq:{default}:active` | list | Tasks that a worker is processing now. |\n| `asynq:{default}:lease` | sorted set | The lease expiry time of each active task. |\n| `asynq:{default}:t:<task-id>` | hash | The task: `msg`, `state`, and `pending_since`. |\n| `asynq:queues` | set | The names of the queues. |"
    },
    {
      "id": "what-happens-to-a-task-when-a-server-is-killed",
      "title": "What happens to a task when a server is killed",
      "role": "content",
      "text": "A server holds a lease on each active task and renews it while it works. After a server\nrunning a 60-second task was stopped with `kill -9`, the task stayed in the `active` state\nfor about a minute, because its lease had to expire. Then it moved to `retry`, then to\n`pending`, and a new server ran it again about 73 seconds after the kill. The task went\nthrough the `retry` state, so Asynq treats the lost run as a failed attempt.\n\nAsynq therefore re-runs a task whose server dies, but only after a delay and at least once.\nWrite handlers so that running one twice is safe."
    },
    {
      "id": "more-information",
      "title": "More information",
      "role": "content",
      "text": "- [Asynq on GitHub](https://github.com/hibiken/asynq)"
    }
  ],
  "examples": [
    {
      "id": "requirements-ex0",
      "language": "bash",
      "code": "go get github.com/hibiken/asynq",
      "section_id": "requirements"
    },
    {
      "id": "enqueue-tasks-ex0",
      "language": "go",
      "code": "import (\n    \"encoding/json\"\n    \"time\"\n\n    \"github.com/hibiken/asynq\"\n)\n\nredisOpt := asynq.RedisClientOpt{Addr: \"<your-redis-host>:6379\"}\n\nclient := asynq.NewClient(redisOpt)\ndefer client.Close()\n\npayload, _ := json.Marshal(map[string]any{\"UserID\": 42, \"Greeting\": \"hello\"})\n\n// Run as soon as a worker is free.\ninfo, err := client.Enqueue(asynq.NewTask(\"email:welcome\", payload))\n\n// Retry up to 3 times if the handler returns an error.\nclient.Enqueue(asynq.NewTask(\"email:flaky\", nil), asynq.MaxRetry(3))\n\n// Run no sooner than 3 seconds from now.\nclient.Enqueue(asynq.NewTask(\"email:welcome\", payload), asynq.ProcessIn(3*time.Second))",
      "section_id": "enqueue-tasks"
    },
    {
      "id": "process-tasks-ex0",
      "language": "go",
      "code": "func handleWelcome(ctx context.Context, t *asynq.Task) error {\n    var p struct {\n        UserID   int\n        Greeting string\n    }\n    if err := json.Unmarshal(t.Payload(), &p); err != nil {\n        return err\n    }\n    fmt.Printf(\"Sending welcome to %d: %s\\n\", p.UserID, p.Greeting)\n    return nil\n}\n\nsrv := asynq.NewServer(redisOpt, asynq.Config{Concurrency: 2})\nmux := asynq.NewServeMux()\nmux.HandleFunc(\"email:welcome\", handleWelcome)\nif err := srv.Run(mux); err != nil {\n    log.Fatal(err)\n}",
      "section_id": "process-tasks"
    }
  ]
}
