Introduction

The --init flag for docker run starts a tiny init process as PID 1 inside the container, usually to reap zombie child processes and forward signals correctly. It is often helpful, but it is not always necessary, and it is not a substitute for understanding how your main process behaves. The right question is not whether --init is good or bad. It is whether your container actually needs PID 1 assistance.

What --init Solves

Inside a container, PID 1 has special responsibilities. If your application spawns child processes and does not reap them, zombies can accumulate. PID 1 also receives signals such as SIGTERM, which matters for graceful shutdown.

Using --init inserts a minimal process, commonly tini, to handle those responsibilities.

docker run --init my-image

This is a good default when you are unsure whether the main process handles signals and child cleanup correctly.

When You Usually Do Not Need It

There are several cases where --init adds little or no value:

• the container runs one well-behaved process that does not fork children
• the process already handles signals and child reaping correctly
• the container is short-lived and exits immediately after a single task

For example, a container that runs one simple command and then exits usually does not need an init helper.

docker run --rm alpine echo hello

In a case like this, adding --init is mostly harmless, but it does not solve a real problem.

When It Is the Wrong Mental Model

--init is a tiny process reaper, not a full supervisor. Do not use it as a replacement for:

• process orchestration
• restarting failed workers inside the same container
• running multiple unrelated long-lived services in one container
• complex service management

If the container is trying to behave like a virtual machine with several daemons, --init will not make that design clean. It only improves signal handling and zombie reaping.

Watch for Images That Already Include an Init Layer

Some images already use tini, dumb-init, or another entrypoint that behaves as PID 1. In those cases, adding --init may be redundant.

Check the image entrypoint before assuming you need another init layer. If the image is already designed to handle child processes and signals correctly, --init does not buy much.

Prefer Explicit Process Design

The best long-term fix is often to make the container's main process behave correctly by itself. For example, if you wrap your application in a shell script that forgets to exec the final command, signal handling becomes harder than it needs to be.

A better entrypoint script looks like this:

1#!/bin/sh
2set -eu
3
4exec my-server --port 8080

Using exec makes the server become PID 1 directly, which often avoids part of the shutdown problem.

Common Pitfalls

• Treating --init as mandatory for every container instead of asking whether the process model needs it.
• Assuming --init is a full supervisor for multiple services running inside one container.
• Adding --init on top of an image that already includes its own init-style entrypoint.
• Using wrapper shell scripts that fail to exec the real process, then expecting --init to clean up all signal-handling issues.
• Ignoring the actual behavior of the application and relying on container flags alone to fix process design problems.

Summary

• '--init is helpful when the container process needs assistance with signal forwarding or zombie reaping.'
• It is usually unnecessary for simple single-process containers that already behave well.
• It is not a replacement for a proper supervisor or a clean one-process-per-container design.
• Check whether the image already includes tini or a similar entrypoint before adding it again.
• The best answer is often to design the container entrypoint and main process correctly first, then add --init only when it solves a real issue.