Self-hosted service
Yelp/dumb-init avatar
Yelp/dumb-init

dumb-init and the PID 1 problem: what the small C init actually changes

A minimal init system for Linux containers

7,318 stars354 forksPythonMIT

At a glance

What is it?
dumb-init is a single statically linked binary that takes the PID 1 slot inside a container and proxies signals to one command. Here is what its setsid default, --single-child switch and --rewrite mapping do, and where each of them stops short.
Who is it for?
Reach for dumb-init when a container runs one long lived process that has to stop cleanly and nothing above it sends the signal that process wants. Skip it when you need restart policies, per service configuration, or a supervisor that survives the death of the main process.
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 last received commits 13 days ago.
What is it written in?
Mainly Python, 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

  • Yelp/dumb-init7,318 ★ · +7
Star history
Repository2026-09-232026-11-15
Yelp/dumb-init7.3k7.3k

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

Editorial analysis

SIGTERM to a process that registered no handler does nothing at PID 1

The kernel treats PID 1 differently from every other process. When a signal arrives at an ordinary process, the kernel first looks for a handler the process registered and falls back to the default action when none exists, which is why SIGTERM kills a normal program. If that signal lands on PID 1 and nothing was ever registered, the fallback is skipped and nothing happens at all. A container entrypoint that ignores SIGTERM is not broken, it is following the PID 1 rule.

The failure is easiest to see in CI. A job that runs `docker run my-container script` and then receives SIGTERM typically kills the `docker run` command while the container keeps running in the background, because the signal reached the client rather than the process inside. dumb-init claims the PID 1 slot itself, spawns your command as a child, and forwards what it receives. Your process then takes signals as an ordinary child, so the default handlers you expected finally apply.

Zombies collect under PID 1 because most parents never call wait()

A process that exits stays in the process table as a zombie, or defunct, until its parent calls some variation of `wait()` on it. When a parent exits before its child, the child is orphaned and re-parented under PID 1, which makes the init system responsible for reaping it. Programs do not `wait()` on processes that merely become attached to them, so containers routinely finish their lives with dozens of zombies rooted at PID 1.

dumb-init answers that structurally rather than through configuration. It holds PID 1, launches exactly one process, and stays alive as the parent of whatever that process leaves behind. When your process dies, dumb-init dies too, taking care to clean up other processes that might still remain. There is also no restart path, since the stated behavior is that dumb-init follows its child out. Anything that must come back after a crash belongs to a layer above this one.

setsid by default, so one signal reaches the whole process group

In its default mode dumb-init establishes a session rooted at the child and delivers signals to the entire process group rather than to the single process it launched. That is the setting you want when the child is a shell script, because a shell that receives SIGTERM does not pass it on: the shell dies and the servers it started keep running, both the backgrounded one and the one in the foreground.

Putting dumb-init in the shebang line repairs that for scripts outside a container as well, which is why the project mentions process supervisors such as daemontools and supervisord as places the same trick pays off. The script form from the project's own example is the shortest first run:

bash
#!/usr/bin/dumb-init /bin/sh
my-web-server &  # launch a process in the background
my-other-server  # launch another process in the foreground

Prefixing a normal command is the same idea without the shebang: dumb-init goes in front of the command and the rest of the line is passed through untouched.

--single-child and DUMB_INIT_SETSID=0 hand the leak back to you

Passing `--single-child`, or setting the environment variable `DUMB_INIT_SETSID=0`, narrows delivery to the direct child only. That mode is described as completely transparent, and copies can even be chained, as in `dumb-init dumb-init echo 'oh, hi'`.

The cost is that everything below the first process is out of reach again. A shell script that backgrounds a server loses the group signal, the server is never told to stop, and the container ends with an orphan, which is the exact failure dumb-init was added to prevent. Use this mode only when the child forwards signals itself, and expect to own the grandchild problem in writing.

The job control rewrites belong to the setsid side of the switch as well. Converting SIGTSTP, SIGTTIN and SIGTTOU into SIGSTOP is described as behavior for setsid mode. Two switches that read as a small change to signal delivery in fact move you back toward the bare PID 1 behavior the tool exists to prevent.

--rewrite 15:3 means you already know the stop signal

Some applications will not shut down on SIGTERM, and some Docker supervisors, Mesos and Kubernetes named in the docs, always send one standard signal no matter what the image needs. dumb-init can rewrite an incoming signal number before proxying it: `--rewrite 15:3` turns SIGTERM (number 15) into SIGQUIT (number 3), and rewriting to the special number `0` drops the signal so the child never receives it.

Nothing is discovered for you. The mapping is a pair of numbers you supply, so a wrong number means the application's cleanup path never runs and the stop looks like a hang until the orchestrator's grace period runs out and the container is killed outright. Dropping to `0` fails in the other direction, since the child is told nothing at all, which is only correct for processes that finish on their own. The same mechanism is the way out of the SIGSTOP behavior described next: rewrite the job control signals back to their original values.

dumb-init suspends itself on job control signals even after you rewrite them

Forwarding SIGTSTP, SIGTTIN or SIGTTOU is not sufficient in setsid mode. If the process has no custom handler for these signals, the kernel does not apply the default handling, which would be suspending the process, because the process is a member of an orphaned process group. For that reason dumb-init installs default rewrites from those three signals to SIGSTOP, and you can opt out by rewriting them back to their original values.

The stated caveat is worth planning around: for the job control signals dumb-init will always suspend itself after receiving the signal, even if you rewrote it to something else. Rewriting changes what the child receives, not what the supervisor does to itself. A workload that depends on real job control semantics therefore stops the supervisor as well as the child, and proxying pauses until something continues it. Rewriting never restores the kernel default, it substitutes a different signal.

apt install dumb-init hands you a binary that will not travel

On Debian and its derivatives the package sits in the official repositories, Debian since stretch and Ubuntu since bionic, so installation is an ordinary package install:

bash
apt install dumb-init

Those repository versions carry a warning that matters once you build images: most of them are not statically linked, unlike the binaries the project builds, so a copy generally will not run on another Linux distribution. A Dockerfile that extracts the executable from a Debian build stage and drops it into a different base image is the case that breaks, and the failure arrives at start time as a missing loader or library rather than at build time. Take a statically linked build for anything that crosses distributions. The project's own Debian package installs the binary at /usr/bin/dumb-init, which is the path the shebang example assumes.

One C file behind a Python wheel, built by a Makefile that fans out

The supervisor is one C source file, and the default build flags are in the Makefile:

bash
CFLAGS=-std=gnu99 -static -s -Wall -Werror -O3

`make build` compiles dumb-init.c and depends on a generated header, since the Makefile turns the VERSION file into VERSION.h with xxd first. Everything around that is distribution work: `python setup.py sdist` followed by manylinux2014 containers per architecture and auditwheel repair produce the wheel, `debuild --set-envvar=CC=musl-gcc` produces the Debian package, and the release target writes sha256sums for the resulting files. The repository reports Python as its primary language, yet the wheel contains no Python source at all, which is why setup.py marks the distribution as not pure and tags it py2.py3 with no ABI. There is nothing to import. Tests live in tests/ and testing/ with pytest.ini and tox.ini alongside circle.yml. The last push is dated 2026-10-19 on the default branch master, while the newest tag in the archive is v1.2.5 from 2021-02-02, after v1.2.4 on 2020-12-07 and v1.2.3 on 2020-12-03. The code moves faster than the releases, so pin the tag you tested.

Editorial conclusion

Reach for dumb-init when a container runs one long lived process that has to stop cleanly and nothing above it sends the signal that process wants. Skip it when you need restart policies, per service configuration, or a supervisor that survives the death of the main process. Before deploying, pin a release tag instead of tracking master: the newest tag in the archive is v1.2.5 from 2021-02-02, and the package your distribution ships is usually not statically linked, so confirm your base image can run the binary you copied.

Frequently asked questions

What is dumb-init?

A small statically linked binary written in C that runs as PID 1 in a container. It launches one process and proxies the signals it receives to a session rooted at that child, so the child's default signal handlers apply.

what does dumb init do

It holds the PID 1 slot, spawns your command as a child, and forwards signals to a session or process group around it. If your process dies, dumb-init dies too and cleans up processes that might still remain.

what is usr bin dumb init

That is where the project's Debian package installs the binary, and it is the path the shebang example relies on: #!/usr/bin/dumb-init /bin/sh. Packages from a distribution repository are not usually statically linked.

What does init mean in Linux?

The first process, PID 1. The kernel applies special signal handling to it, and orphaned children are re-parented under it, so it has to reap zombies. Without one, containers end with defunct processes and signals go nowhere.

Is init still used today?

Lightweight containers popularized running a single process or service with no systemd or sysvinit around it. The project argues that dropping an init leaves containers that cannot be stopped gracefully and containers that leak instead of being destroyed.

Official sources

  1. License: MIT
  2. Project website
  3. README
  4. Releases
  5. Yelp/dumb-init 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/yelp-dumb-init.svg)](https://hysenlabs.com/projects/yelp-dumb-init)

Star history chart for your README

markdown
[![Star history](https://hysenlabs.com/chart/yelp-dumb-init.svg)](https://hysenlabs.com/projects/yelp-dumb-init)

Was this useful?