Guide · Open source
How to use asynq: queue and process background tasks in Go
Updated · written with AI from the project's own documentation and checked against our catalogue data
Asynq is a Go library for putting jobs on a queue and letting separate worker processes run them in the background, such as sending emails or resizing images. It stores the queue in Redis, so several machines can share the work. This guide shows you how to install it, define a task, enqueue work and run a worker that processes it.
Asynqhibiken/asynq · ★ 13.8k · MIT Install options & downloads Quick start
- 1Check prerequisites. Install Go and make sure a Redis server version 4.0 or higher is running locally or in Docker.
- 2Create a Go module. Make a project folder and run go mod init with your own module path inside it.
- 3Install Asynq. Run go get -u github.com/hibiken/asynq in the project folder.
- 4Write task constructors and handlers. Define task type constants, payload structs, a NewXXXTask function and a handler that processes the payload.
- 5Enqueue tasks. Create an asynq.NewClient with your Redis address and call Enqueue, optionally with ProcessIn or other options.
- 6Run a worker. Start a worker server that pulls tasks from Redis and runs your handlers. Follow the README for the full server setup.
What you need before installing Asynq
Asynq is a Go library, so you need Go installed. The README says the last two Go versions are supported. You also need a Redis server, version 4.0 or higher, running either locally or in a Docker container.
- Go (the last two Go versions are supported)
- Redis 4.0 or higher, running locally or in Docker
Install the Asynq library in your Go project
Create a folder for your project and run go mod init inside it, using your own module path. Then install Asynq with go get.
go get -u github.com/hibiken/asynqDefine task types and handlers
A task consists of a type and a payload. The README suggests writing a function named NewXXXTask to create a task and a handler named HandleXXXTask to process it. The payload is usually JSON, and a handler returns an error if processing fails. Wrapping an error with asynq.SkipRetry tells Asynq not to retry it, which is useful when the payload cannot be parsed.
- Give each task a string type, such as email:deliver
- Create the task with asynq.NewTask, passing the type and payload
- A handler can be a plain function or a type that implements the asynq.Handler interface
func NewEmailDeliveryTask(userID int, tmplID string) (*asynq.Task, error) {
payload, err := json.Marshal(EmailDeliveryPayload{UserID: userID, TemplateID: tmplID})
if err != nil {
return nil, err
}
return asynq.NewTask(TypeEmailDelivery, payload), nil
}Enqueue tasks with a Client
In your application code, create a Client that points at your Redis address and use its Enqueue method to put a task on a queue. Tasks are processed immediately by default. To run a task later, pass the ProcessIn or ProcessAt option. Other options include MaxRetry, Queue, Timeout, Deadline and Unique.
- Use ProcessIn for a relative delay, or ProcessAt for a specific time
- Options passed at enqueue time can override options set in NewTask
client := asynq.NewClient(asynq.RedisClientOpt{Addr: "127.0.0.1:6379"})
defer client.Close()
info, err := client.Enqueue(task, asynq.ProcessIn(24*time.Hour))Run workers to process tasks
Worker servers pull tasks off queues and start a worker goroutine for each task, so tasks are processed concurrently. You can run several worker servers on different machines against the same Redis instance to spread the work. The source excerpt is truncated before the worker setup code, so check the README and the Go package documentation for the full server example.
- Multiple worker servers can share one Redis instance
- Tasks are processed concurrently by multiple workers
Use retries, priority queues and monitoring
Asynq's feature list includes retries of failed tasks, automatic recovery of tasks after a worker crash, weighted and strict priority queues, scheduled and periodic tasks, and task timeouts and deadlines. It also has a web UI and a command-line tool to inspect and remote-control queues and tasks, plus Prometheus integration for metrics.
Asynq guarantees at least one execution of a task, which means a task may run more than once, so handlers should be written to tolerate repeats.
- Retries of failed tasks
- Weighted and strict priority queues
- Periodic tasks and scheduling
- Web UI and CLI for inspection
- Prometheus integration for queue metrics
What people use it for
- Sending emails in the background after a user action
- Resizing or processing images without blocking a web request
- Running scheduled jobs that should execute later, such as a reminder after 24 hours
- Spreading heavy work across several worker machines that share one Redis instance
Frequently asked questions
Is asynq free to use?
Yes. Asynq is released under the MIT licence, as shown in the project's metadata and the README badge. Check the LICENSE file in the repository for the full terms.
What are the requirements for asynq?
You need Go, with the last two Go versions supported, and Redis version 4.0 or higher running locally or in Docker. The README says Asynq is a Go library and only shows Go usage.
How do I install asynq?
Run go get -u github.com/hibiken/asynq inside your Go project. Create the project with go mod init first if you do not have a module yet.
Does asynq work with Redis Cluster?
The README warns that some of the Lua scripts in the library may not be compatible with Redis Cluster. Check this carefully before using a cluster setup.
Can I use asynq in a project that is not written in Go?
No. Asynq is a Go library, and the README only shows Go usage. Non-Go projects would need a different tool.
What are the alternatives to asynq?
The project lists Machinery, Temporal, River and Faktory as comparable projects. This guide does not compare their features, so read each project's documentation before choosing.
New agent skills, repos and AI tools — every week
The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.
Our verdict
Asynq suits Go developers who already run Redis and want retries, scheduling and priority queues without building them. It is a poor fit for non-Go projects, for setups that depend on Redis Cluster, or for teams that need a stable v1 API, since the README says the public API could change before v1.0.0.
Install options & downloads