Self-hosted service
testcontainers/testcontainers-dotnet avatar
testcontainers/testcontainers-dotnet

Testcontainers for .NET spins throwaway containers inside the test run

A library to support tests with throwaway instances of Docker containers for all compatible .NET Standard versions.

4,376 stars365 forksC#MIT

At a glance

What is it?
Testcontainers for .NET supports tests with throwaway instances of Docker containers, built on top of the .NET Docker Remote API. It is a good fit for integration tests that need real backing services, and a poor fit for pipelines without a container runtime.
Who is it for?
Adopt it when your .NET suite needs real services in throwaway Docker containers rather than an in-memory stand-in, and skip it if your pipeline forbids container runtimes. Before the first commit, check that Docker is reachable from the agent that runs the build, because that single dependency, not the API, decides whether the tests pass.
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 C#, 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-dotnet4,376 ★ · +14
Star history
Repository2026-09-232026-11-15
testcontainers/testcontainers-dotnet4.4k4.4k

14 Stars in the last 53 days, measured from the daily GitHub snapshot. Compare with other projects

Editorial analysis

A fixture that owns the container lifetime

Testcontainers for .NET is a library to support tests with throwaway instances of Docker containers for all compatible .NET Standard versions.

The audience is narrow and specific: .NET developers writing tests that talk to something stateful. A unit test that exercises a calculator does not need this. A test that inserts a row, checks a constraint, or publishes to a topic and reads it back does, because the behaviour being verified lives in the server, not in the client library.

Built on the .NET Docker Remote API, not on Compose

The mechanism matters for how failures surface. Testcontainers for .NET is a client of the .NET Docker Remote API. There is no compose file, no YAML orchestration layer and no separate process to supervise. The library is what the README calls a lightweight implementation, and it keeps that promise by owning one thing: the container handle.

Where to get the package, and how a first fixture reads

The repository does not print a dotnet add package line. It points at the NuGet listing for Testcontainers and at the documentation site at dotnet.testcontainers.org.

Every fixture needs a Docker daemon it did not ask for

The library requires a running container runtime, and it cannot supply one.

Worse, the dependency is invisible in the code. A test file that constructs a container looks like any other test file, so the requirement that the build agent speak to a Docker socket propagates outward into pipeline configuration without appearing anywhere in the pull request that caused it.

Image tags are the version pin nobody reviews

A fixture names an image. In most cases that image also carries a tag, and a tag such as latest resolves to a different digest on a different day. The result is a suite that passed on Tuesday and fails on Thursday because a database release changed default behaviour, with the diff pointing at your assertion rather than at the dependency. Pinning explicit version tags in fixtures is the cheapest defence, and it is the one piece of discipline this library cannot enforce for you.

The same caution applies to module versions against the core package. The repository carries Directory.Packages.props and global.json, which tells you the project itself treats its own dependency graph as something worth pinning. Emulating that discipline in your test fixtures costs nothing.

Where Docker Compose and Aspire split from this approach

Docker Compose orchestrates declared services before the suite starts and keeps them alive across it. That is the right shape for an application whose own code needs several dependencies, because the topology lives in a versioned YAML file your developers can read.

Documentation lives off the repository, so version drift is your problem

The repository root is a project tree, not a tutorial. Entries such as docs/, examples/, mkdocs.yml and requirements.txt show a documentation site built with MkDocs and served through a python:3.8-alpine compose service on port 8000. The example projects listed are Flyway, Respawn and WeatherForecast, which tells you the intended audience better than any feature list: teams running migrations, seeding and realistic web tests against real backing services.

The catch is that the useful content sits behind that site rather than in the README, so version drift between what you read and what your packages do is possible. The last push to the default develop branch was on 2026-10-29, with releases 4.14.0, 4.15.0 and 4.16.0 landing between August and October 2026, and the MIT licence puts no restriction on commercial use.

Editorial conclusion

Adopt it when your .NET suite needs real services in throwaway Docker containers rather than an in-memory stand-in, and skip it if your pipeline forbids container runtimes. Before the first commit, check that Docker is reachable from the agent that runs the build, because that single dependency, not the API, decides whether the tests pass. Then pin image tags in every fixture. Measure one cold-cache run before you commit to it.

Frequently asked questions

What is Testcontainers for .NET and what is it used for?

It is a library for tests that need throwaway instances of Docker containers, working across the compatible .NET Standard versions. It is built on the .NET Docker Remote API and provides a lightweight implementation to support your test environment.

Do I need Docker to run Testcontainers for .NET?

The library drives the Docker Remote API to create and destroy containers, so a reachable Docker runtime is required to run the fixtures. If your build agent cannot reach a daemon, the container-based tests cannot start.

How can I test Docker containers in a .NET test project?

The project ships a library that starts and disposes containers for you instead of a separate orchestration file.

Official sources

  1. License: MIT
  2. Project website
  3. README
  4. Releases
  5. testcontainers/testcontainers-dotnet on GitHub

Was this useful?