Guide · Open source
How to use ants: a Go goroutine pool tutorial
Updated · written with AI from the project's own documentation and checked against our catalogue data
ants is an open-source Go library that implements a goroutine pool with fixed capacity. It recycles goroutines so your program can cap how many run at once, instead of spawning them without limit. This guide is for Go developers who want to install ants, create a pool, submit tasks and adjust the pool while the program runs.
antspanjf2000/ants · ★ 14.5k · MIT Install options & downloads Quick start
- 1Check your Go version. Confirm you have Go 1.19 or newer, as the README badge indicates.
- 2Install ants v2. Run the go get command for github.com/panjf2000/ants/v2 with GO111MODULE=on.
- 3Create a pool. Call ants.NewPool with the capacity you want, and check the returned error.
- 4Submit tasks. Pass each unit of work as a function to ants.Submit or to your pool.
- 5Tune or release. Use Tune to change capacity while running, and Release or ReleaseTimeout when finished.
What ants does and when to use it
ants manages and recycles a large number of goroutines, letting you limit how many are running in a concurrent program. It is aimed at programs that would otherwise create goroutines without bound, and at workloads that submit many short tasks and benefit from reusing workers.
The README also notes that ants can handle panics gracefully so a program does not crash, and that it offers a non-blocking mechanism and optional preallocated memory.
- Limit concurrent goroutines in a service
- Reuse workers when submitting many short tasks
- Handle panics in tasks without crashing the program
- Resize the pool at runtime
Install ants v2 in a Go project
ants requires Go. The README badge indicates Go 1.19 or newer. Install the v2 module with the go get command shown in the README. The README gives the GO111MODULE=on setting for v2 installs.
The README also lists a command for v1, but the v2 path is the one to use for new code.
go get -u github.com/panjf2000/ants/v2Create a pool with a fixed capacity
Call NewPool with the number of goroutines you want the pool to hold. The README example creates a pool with capacity 10000. NewPool returns a pool and an error, which the example ignores with a blank identifier; in real code, check the error.
To customize behavior, pass options to NewPool, NewPoolWithFunc or NewPoolWithFuncGeneric. The README points to the ants.Options and ants.Option documentation for the full list.
p, _ := ants.NewPool(10000)Submit tasks to the pool
Submit work with ants.Submit. Each task is a function. The README shows the call with an empty function as the simplest form. Replace the empty function with your real work. The README points to the pkg.go.dev examples for complete basic usage.
ants.Submit(func(){})Tune the pool capacity at runtime
Use Tune on a pool to change its capacity while the program runs. The README says the method is thread-safe, so you do not need extra locking when calling it from multiple goroutines.
Tune can raise or lower the capacity.
pool.Tune(1000) // Tune its capacity to 1000
pool.Tune(100000) // Tune its capacity to 100000Preallocate the queue for large, long-running workloads
ants can preallocate the memory of the goroutine queue. The README says this may improve performance in specific cases: a pool with very large capacity where each task runs for a long time. In that case, preallocation reduces memory allocation in the queue. It is optional, so for ordinary workloads you can leave it off.
Pass the WithPreAlloc option to NewPool. The README says the whole capacity is allocated when NewPool is called.
p, _ := ants.NewPool(100000, ants.WithPreAlloc(true))Release and reboot a pool
Call Release when you are done with a pool. ReleaseTimeout waits up to a given duration before releasing. The README says a released pool can still be used after calling Reboot.
pool.Release()
pool.ReleaseTimeout(time.Second * 3)
pool.Reboot()Know the limits: task order is not guaranteed
Tasks submitted to an ants pool are not guaranteed to run in submission order. They are spread across concurrent workers, so they run concurrently. If your work must happen in strict sequence, ants is the wrong tool, or you need your own ordering logic.
ants is written for Go only, so it does not fit non-Go projects.
What people use it for
- Limiting how many goroutines a web service runs at once
- Processing a large queue of short tasks with reused workers
- Running long tasks in a large pool with preallocated queue memory
- Keeping a service running when a task panics, using the built-in panic handling
Frequently asked questions
Is ants free to use?
Yes. The source code is available under the MIT License, as stated in the README license section.
What do I need to use ants?
You need Go. The README badge indicates Go 1.19 or newer. ants is written for Go only.
How do I install ants?
Run go get -u github.com/panjf2000/ants/v2 with GO111MODULE=on, as the README shows for v2.
Does ants run tasks in order?
No. The README says task order is not guaranteed because tasks run concurrently across workers. Use your own ordering logic if sequence matters.
What are alternatives to ants?
The README lists comparable projects: Go's built-in worker pool patterns using channels and sync.WaitGroup, tunny, and workerpool. Choose based on your needs.
Can I change the pool size after creating it?
Yes. Call Tune on the pool with a new capacity. The README says this method is thread-safe.
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
ants suits Go developers who need to cap concurrent goroutines in a service, or who submit many short tasks and want worker reuse. It is a poor fit for non-Go projects, for work that must run in strict order, or for developers who are still learning basic Go concurrency.
Install options & downloads