Why does creating a custom network start Ryuk (ResourceReaper) immediately?

[JaySabva]

I’m seeing testcontainers/ryuk start as soon as I create a custom network, even when launching a single container. In CreateNetworkCmd setup, Testcontainers calls ResourceReaper.instance().getLabels() to
add cleanup labels:

labels.putAll(DockerClientFactory.DEFAULT_LABELS);
//noinspection deprecation
labels.putAll(ResourceReaper.instance().getLabels());
createNetworkCmd.withLabels(labels);

This call appears to initialize ResourceReaper, which starts Ryuk even when reuse is enabled. Is this expected? Is there a way to avoid starting Ryuk when creating a network (without globally disabling Ryuk or relying on reuse)?

[rameshreddy-adutla]

This is by design! Here's why:

Ryuk (ResourceReaper) is the cleanup safety net. Its job is to ensure that Docker resources (containers, networks, volumes) created by Testcontainers are cleaned up even if your JVM crashes or tests are killed.

When you call Network.newNetwork(), Testcontainers adds cleanup labels to the Docker network:

labels.putAll(ResourceReaper.instance().getLabels());

Calling ResourceReaper.instance() triggers lazy initialization — this is the first time Testcontainers needs the Ryuk session ID to generate labels. The session ID is created by Ryuk at startup, so Ryuk must be running before any labeled resource is created.

Why not defer Ryuk until a container starts?
Because networks are also Docker resources that need cleanup. If your test creates a network but crashes before creating any container, Ryuk needs to already be running to clean up that orphaned network.

If you want to avoid early Ryuk startup:

1. Use @Testcontainers annotation — it manages lifecycle for you
2. Set TESTCONTAINERS_RYUK_DISABLED=true (only in CI where containers are cleaned up by the environment)
3. Avoid creating networks before containers — let Testcontainers handle networking

The overhead of Ryuk starting early is minimal (~1-2s, ~12MB RAM). It's a small price for guaranteed cleanup.

[MILLERMARRU]

This is by design, and the reason is important: Ryuk needs to know about every Docker resource from the moment it is created, not just containers.

When you call Network.newNetwork(), Testcontainers immediately adds cleanup labels to the network object in Docker. For Ryuk to track and clean up that network on JVM exit (or crash), it must be running before those labels are applied - so it starts as soon as the first labelable resource is created.

Why this matters even with reuse enabled:
Reuse (withReuse(true)) only keeps containers alive between test runs; it does not remove them from Ryuk's tracking. If the JVM is killed without a graceful shutdown, Ryuk is the only guarantee that the network gets cleaned up.

If you need to avoid Ryuk (e.g., CI environments with their own cleanup), you can disable it globally:

# testcontainers.properties
ryuk.disabled=true

Or via environment variable:

TESTCONTAINERS_RYUK_DISABLED=true

Disabling Ryuk means you are responsible for cleaning up Docker resources if the JVM exits abnormally. For ephemeral CI runners this is fine, but for local development it can leave orphaned networks and containers.

There is no API to selectively prevent Ryuk from starting for one specific Network.newNetwork() call - it is intentionally all-or-nothing to preserve the cleanup guarantee.