Dumb-Init

1.2.5.post1 · active · verified Wed Apr 15

Dumb-init is a minimal init system for Linux containers, designed to run as PID 1. It acts as a simple process supervisor, properly handling signals sent to the container and reaping orphaned zombie processes, which is crucial for the graceful shutdown of applications and preventing resource leaks. The current version is 1.2.5.post1, and it maintains a steady, albeit infrequent, release cadence with minor updates and bug fixes.

Warnings

gotcha Processes running as PID 1 in Linux containers (e.g., Docker) have special kernel behavior and do not correctly handle signals (like SIGTERM) or reap zombie child processes by default. Failing to use an init system like `dumb-init` can lead to containers that cannot be gracefully stopped or accumulate defunct processes.
Fix: Always use `dumb-init` (or a similar init system like `tini`) as your container's `ENTRYPOINT` with JSON array syntax. For example: `ENTRYPOINT ["dumb-init", "--"]`.
breaking Versions 1.2.2 and later changed the naming convention for pre-built binaries from Debian architecture names (e.g., `amd64`, `arm64`) to Linux kernel names (e.g., `x86_64`, `aarch64`). While older names might be kept for compatibility in some Debian packages, this could affect custom build systems or scripts relying on specific binary names.
Fix: Update references to binary names in build scripts or Dockerfiles if you are directly accessing the `dumb-init` binary by its architecture-specific name, or ensure your package manager handles the aliasing.
gotcha Using the 'shell form' for `ENTRYPOINT` or `CMD` (e.g., `ENTRYPOINT dumb-init -- python my_app.py`) will cause `sh -c` to become PID 1, not `dumb-init`. This defeats the purpose of `dumb-init` as the shell will not correctly forward signals.
Fix: Always use the JSON array (exec form) syntax for `ENTRYPOINT` and `CMD` when using `dumb-init` to ensure it is PID 1. Example: `ENTRYPOINT ["dumb-init", "--"]` and `CMD ["python", "my_app.py"]`.
gotcha A race condition in versions prior to 1.2.2 could cause the child process to receive SIGHUP and SIGCONT signals very shortly after startup, particularly in some container or virtualization environments.
Fix: Upgrade to `dumb-init` version 1.2.2 or newer to mitigate this race condition.
gotcha Installation of `dumb-init` (version 1.2.5.post1) has been reported to fail on macOS with Python 3.12.4 and Poetry, likely due to issues with PEP 517 builds.
Fix: Consider using an earlier Python version or a different dependency manager on macOS, or consult the GitHub issues for potential workarounds or newer fixes if this specific environment is required.

Install

pip install dumb-init Install via pip

Quickstart

This Dockerfile demonstrates how to install and use `dumb-init` as the entrypoint for a Python application. `dumb-init` will become PID 1, properly forwarding signals to `my_app.py` and reaping any zombie processes. Ensure your `CMD` also uses JSON array syntax.

FROM python:3.9-slim-buster

# Install dumb-init
RUN pip install dumb-init

WORKDIR /app
COPY my_app.py .

# Use dumb-init as the ENTRYPOINT
# Must use JSON array syntax to ensure dumb-init is PID 1
ENTRYPOINT ["dumb-init", "--"]

# Your actual application command
CMD ["python", "my_app.py"]

view raw JSON →