Self-hosted service
testcontainers/testcontainers-go avatar
testcontainers/testcontainers-go

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.

5,033 stars659 forksGoMIT

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.

From daily snapshots

Star history

  • testcontainers/testcontainers-go5,033 ★ · +42
Star history
Repository2026-09-232026-11-15
testcontainers/testcontainers-go5k5k

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.

go
module github.com/testcontainers/testcontainers-go

go 1.26.0

toolchain go1.26.10

cleanup.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.

go
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.0

test-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.

make
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-modules

serve-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.

make
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

  1. License: MIT
  2. Project website
  3. README
  4. Releases
  5. testcontainers/testcontainers-go on GitHub
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.

Add this badge to your README

markdown
[![Hysen Labs](https://hysenlabs.com/badge/testcontainers-testcontainers-go.svg)](https://hysenlabs.com/projects/testcontainers-testcontainers-go)

Star history chart for your README

markdown
[![Star history](https://hysenlabs.com/chart/testcontainers-testcontainers-go.svg)](https://hysenlabs.com/projects/testcontainers-testcontainers-go)

Was this useful?