Testcontainers for Go: what the repository root actually hands you
Testcontainers for Go is a Go package that makes it simple to create and clean up container-based dependencies for automated integration/smoke tests. The clean, easy-to-use API enables developers to programmatically define containers that should be run as part of a test and clean up those resources when the test is done.
At a glance
- What is it?
- The root repository is a Go library for starting container dependencies inside tests, wrapped in a docs site, a mock generator, and separately maintained module subtrees. Here is what each piece means for a reader wiring it into a suite.
- Who is it for?
- Take it if your Go suite needs real container dependencies and every runner you care about already has a container runtime. Leave it if that runtime is not guaranteed, because the Docker client dependency is not optional here.
- Can I use it commercially?
- Yes. MIT is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository received new commits within the last day.
- What is it written in?
- Mainly Go, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on November 15, 2026, and from our analysis. They are not legal advice.
Star history
- testcontainers/testcontainers-go5,033 ★ · +42
| Repository | 2026-09-23 | 2026-11-15 |
|---|---|---|
| testcontainers/testcontainers-go | 5k | 5k |
42 Stars in the last 53 days, measured from the daily GitHub snapshot. Compare with other projects
Editorial analysis
The root README is a pointer, so the first import comes from the docs site
The root README does one thing well and then hands you off. It names the purpose in a single sentence: testcontainers-go is a Go package that makes it simple to create and clean up container based dependencies for automated integration and smoke tests, where containers are defined programmatically as part of a test and those resources are cleaned up when the test is done. Everything after that is a link. The site golang.testcontainers.org is rendered from the ./docs directory, and the one instruction about adding the dependency points at the quickstart guide. No module path, no container request, no cleanup call appears anywhere in the file. So the first hard fact a reader gets sits in go.mod instead: the module path, the language floor, and the toolchain the build expects.
module github.com/testcontainers/testcontainers-go
go 1.26.0
toolchain go1.26.10cleanup.go and lifecycle.go put teardown on the test side of the fence
The root file list shows the scope of the package without opening a single source file: container.go, generic.go, lifecycle.go, cleanup.go, image.go, network.go, mounts.go, file.go, config.go, generate.go, logconsumer.go, logger_option.go, plus the docker.go, docker_client.go, docker_auth.go and docker_mounts.go group, with exec/, log/, network/, internal/ and docs/ sitting beside them. Two of those names set the terms for how a test ends, because lifecycle.go and cleanup.go are part of the public surface. That is a promise with a cost. The README does not document what happens to started containers if a test binary exits before the cleanup path runs.
docker_client.go and a pinned moby client make the runtime an assumption
The dependency list answers the runtime question. go.mod requires github.com/moby/moby/client v0.6.2 and github.com/moby/moby/api v1.56.1, alongside github.com/containerd/platforms v0.2.1, github.com/cpuguy83/dockercfg v0.3.2, github.com/moby/patternmatcher v0.6.1 and github.com/opencontainers/image-spec v1.1.1. The indirect block adds github.com/docker/go-connections v0.8.2, github.com/ebitengine/purego v0.10.1 and github.com/Microsoft/go-winio v0.6.2, which arrive with the client rather than with your test code. The library therefore talks to a Docker API endpoint, and the tree holds no second client file for another engine. If a runner has no daemon and no socket, the container you asked for is unreachable, and the weight of those packages sits in your test binary either way.
dario.cat/mergo v1.0.2
github.com/cenkalti/backoff/v4 v4.3.0
github.com/containerd/errdefs v1.0.0
github.com/containerd/platforms v0.2.1
github.com/cpuguy83/dockercfg v0.3.2
github.com/google/uuid v1.6.0
github.com/magiconair/properties v1.18.12
github.com/moby/go-archive v0.3.3
github.com/moby/moby/api v1.56.1
github.com/moby/moby/client v0.6.2
github.com/moby/patternmatcher v0.6.1
github.com/opencontainers/image-spec v1.1.1
github.com/shirou/gopsutil/v4 v4.26.6
github.com/stretchr/testify v1.12.1
golang.org/x/crypto v0.58.0
golang.org/x/sys v0.49.0test-all depends on test-unit, which wants a live daemon before a compiler
The Makefile is short and says more than the README does. test-all expands to tools test-tools test-unit, lint-all recurses into modulegen, examples and modules, and tidy-all repeats that shape for module tidying.
include ./commons-test.mk
lint-all:
$(MAKE) lint
$(MAKE) -C modulegen lint
$(MAKE) -C examples lint-examples
$(MAKE) -C modules lint-modules
test-all: tools test-tools test-unit
test-examples:
$(MAKE) -C examples test
tidy-all:
$(MAKE) tidy
$(MAKE) -C examples tidy-examples
$(MAKE) -C modules tidy-modulesserve-docs runs python:3.13 in a container, so the docs need the same runtime
Serving the docs locally through the Makefile takes the same infrastructure as running the tests. The serve-docs target starts DOCS_CONTAINER=mkdocs-container from DOCS_IMAGE=python:3.13, mounts the working tree at /testcontainers-go, publishes port 8000, and runs bash -c with pip install -Ur docs-site/requirements.txt followed by mkdocs serve -f mkdocs.yml -a 0.0.0.0:8000. clean-docs removes that container with docker rm -f. The consequence is that serve-docs cannot run without a container runtime.
DOCS_CONTAINER=mkdocs-container
DOCS_IMAGE=python:3.13
clean-docs:
docker rm -f $(DOCS_CONTAINER) || true
serve-docs:
docker run --rm --name $(DOCS_CONTAINER) -it -p 8000:8000 \
-v $(PWD):/testcontainers-go \
-w /testcontainers-go \
$(DOCS_IMAGE) bash -c "pip install -Ur docs-site/requirements.txt && mkdocs serve -f mkdocs.yml -a 0.0.0.0:8000"go 1.26.0 and toolchain go1.26.8 decide whether your module can consume this
Two lines at the top of go.mod set a floor for everyone downstream: go 1.26.0 and toolchain go1.26.10. Your own module has to accept that toolchain before a single container is created, so a project pinned to an older language line cannot add this dependency without moving its own directive first. The same root carries go.sum, a .golangci.yml for linting, a .mockery.yaml for generated mocks, and commons-test.mk, which the Makefile includes on its first line. The README also links a Codespaces button aimed at .devcontainer/devcontainer.json on a standardLinux32gb machine, which is the only written account of a working development environment.
modules/ and examples/ move separately, so a pasted snippet can drift from your pin
test-examples, lint-examples and tidy-examples all recurse into examples/, and the only example paths in the tree are examples/Makefile and examples/nginx/. The modules/ directory is handled the same way, as its own Go module with separate tidy and lint targets. The Makefile comments go further: goals named compose-clean, compose-clone, compose-replace, compose-spec-replace, compose-tidy and compose-test-all-latest clone the compose and compose-go repositories into .build and replace those dependencies, so the compose module is tested against the latest upstream rather than a frozen copy. Two readers get hurt by that arrangement. A snippet copied from the quickstart can describe a version other than the one your go.mod pins, and the compose path is validated against moving upstream branches, so its behavior can shift while your dependency set stays fixed.
Editorial conclusion
Take it if your Go suite needs real container dependencies and every runner you care about already has a container runtime. Leave it if that runtime is not guaranteed, because the Docker client dependency is not optional here. Before you pin a version, read the quickstart the README links to: the root repository never states which version to require, and the last push landed on 2026-11-02 with v0.44.0 dated 2026-08-07.
Frequently asked questions
What are testcontainers-go containers used for?
For container based dependencies in automated integration and smoke tests. A Go test defines the containers programmatically, and those resources are cleaned up when the test is done.
Can I use testcontainers-go without Docker?
The dependency list points at the Docker API: go.mod requires github.com/moby/moby/client v0.6.2 and github.com/moby/moby/api v1.56.1, and the root holds docker.go, docker_client.go, docker_auth.go and docker_mounts.go. No other engine client appears in the tree.
What kind of test framework is testcontainers-go?
It is not a test runner. It is a Go package that creates and cleans up container based dependencies for automated integration and smoke tests, so the choice of test framework stays with your own suite.
Official sources
Add this badge to your README
If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.
[](https://hysenlabs.com/projects/testcontainers-testcontainers-go)Star history chart for your README
[](https://hysenlabs.com/projects/testcontainers-testcontainers-go)Was this useful?