ENABLE_UNSHARE_PID is set but unshare binary not found. Inst

Error message

ENABLE_UNSHARE_PID is set but unshare binary not found.
Install util-linux package or set ENABLE_UNSHARE_PID=false

What it means

With ENABLE_UNSHARE_PID enabled, the worker probes for the `unshare` binary (from util-linux) before starting. If the probe fails with ErrorKind::NotFound — i.e. the binary is not installed in the container — the worker panics at startup, because PID-namespace isolation is impossible without it.

Source

Thrown at backend/windmill-worker/src/worker.rs:508

                    );
                }

                tracing::error!(
                    "unshare test command failed (exit code: {}). stderr: '{}'. flags: '{}'. \
                    Unshare isolation will NOT be available. \
                    If job_isolation is set to 'unshare' in Instance Settings, jobs will run without isolation. \
                    Common causes: user namespaces disabled (sysctl kernel.unprivileged_userns_clone=0), \
                    max_user_namespaces=0, or missing privileges (--mount-proc requires privileged mode).",
                    output.status,
                    stderr.trim(),
                    flags
                );
                None
            },
            Err(e) => {
                if *ENABLE_UNSHARE_PID {
                    if e.kind() == std::io::ErrorKind::NotFound {
                        panic!(
                            "ENABLE_UNSHARE_PID is set but unshare binary not found.\n\
                            Install util-linux package or set ENABLE_UNSHARE_PID=false"
                        );
                    } else {
                        panic!(
                            "ENABLE_UNSHARE_PID is set but failed to test unshare: {}",
                            e
                        );
                    }
                }

                if e.kind() == std::io::ErrorKind::NotFound {
                    tracing::error!(
                        "unshare binary not found in PATH. Unshare isolation will NOT be available. \
                        Install the util-linux package to enable unshare isolation."
                    );
                } else {
                    tracing::error!(

View on GitHub (pinned to e474e8803c)

Solutions

Install util-linux in the image (`apt-get install -y util-linux` or the alpine equivalent `apk add util-linux util-linux-misc` for the `unshare` binary)
Set ENABLE_UNSHARE_PID=false if PID isolation is not required
Switch to the standard Windmill EE/CE image which ships unshare
Verify with `which unshare` inside the running container

Example fix

// before: Dockerfile based on slim
FROM debian:bookworm-slim
// after
FROM debian:bookworm-slim
RUN apt-get update && apt-get install -y util-linux && rm -rf /var/lib/apt/lists/*

Defensive patterns

Strategy: validation

Validate before calling

// Dockerfile preflight
RUN set -eux; \
    command -v unshare >/dev/null || { echo 'unshare missing: install util-linux'; exit 1; }

Prevention

Always install util-linux when building custom worker images
Add an image smoke test: `docker run <img> unshare --version`
Prefer the official images unless you own the dependency list
If unshare cannot be shipped, set ENABLE_UNSHARE_PID=false explicitly in config

When it happens

Trigger: ENABLE_UNSHARE_PID=true in an image that lacks the `unshare` executable: minimal/distroless base images, custom Dockerfiles built FROM slim images without util-linux.

Common situations: Building a custom worker image from alpine/slim/debian-slim and forgetting util-linux; switching base images during a hardening exercise; using the OSS image where util-linux is trimmed.

Related errors

AI-assisted analysis of windmill-labs/windmill@e474e8803c (2026-09-03). Data as JSON: /api/errors/3472092328517470. Report an issue: GitHub.