OS Manuals

/usr/bin/bwrap

Unprivileged sandboxing tool

From bubblewrap 0.13.1-r0 (os), captured 2026-11-05 by running bwrap --help (exit 0). permalink

usage: /usr/bin/bwrap [OPTIONS...] [--] COMMAND [ARGS...]

    --help                       Print this help
    --version                    Print version
    --args FD                    Parse NUL-separated args from FD
    --argv0 VALUE                Set argv[0] to the value VALUE before running the program
    --level-prefix               Prepend e.g. <3> to diagnostic messages
    --unshare-all                Unshare every namespace we support by default
    --share-net                  Retain the network namespace (can only combine with --unshare-all)
    --unshare-user               Create new user namespace (may be automatically implied if not root)
    --unshare-user-try           Create new user namespace if possible else continue by skipping it
    --unshare-ipc                Create new ipc namespace
    --unshare-pid                Create new pid namespace
    --unshare-net                Create new network namespace
    --unshare-uts                Create new uts namespace
    --unshare-cgroup             Create new cgroup namespace
    --unshare-cgroup-try         Create new cgroup namespace if possible else continue by skipping it
    --userns FD                  Use this user namespace (cannot combine with --unshare-user)
    --userns2 FD                 After setup switch to this user namespace, only useful with --userns
    --disable-userns             Disable further use of user namespaces inside sandbox
    --assert-userns-disabled     Fail unless further use of user namespace inside sandbox is disabled
    --pidns FD                   Use this pid namespace (as parent namespace if using --unshare-pid)
    --uid UID                    Custom uid in the sandbox (requires --unshare-user or --userns)
    --gid GID                    Custom gid in the sandbox (requires --unshare-user or --userns)
    --hostname NAME              Custom hostname in the sandbox (requires --unshare-uts)
    --chdir DIR                  Change directory to DIR
    --clearenv                   Unset all environment variables
    --setenv VAR VALUE           Set an environment variable
    --unsetenv VAR               Unset an environment variable
    --lock-file DEST             Take a lock on DEST while sandbox is running
    --sync-fd FD                 Keep this fd open while sandbox is running
    --bind SRC DEST              Bind mount the host path SRC on DEST
    --bind-try SRC DEST          Equal to --bind but ignores non-existent SRC
    --dev-bind SRC DEST          Bind mount the host path SRC on DEST, allowing device access
    --dev-bind-try SRC DEST      Equal to --dev-bind but ignores non-existent SRC
    --ro-bind SRC DEST           Bind mount the host path SRC readonly on DEST
    --ro-bind-try SRC DEST       Equal to --ro-bind but ignores non-existent SRC
    --bind-fd FD DEST            Bind open directory or path fd on DEST
    --ro-bind-fd FD DEST         Bind open directory or path fd read-only on DEST
    --remount-ro DEST            Remount DEST as readonly; does not recursively remount
    --overlay-src SRC            Read files from SRC in the following overlay
    --overlay RWSRC WORKDIR DEST Mount overlayfs on DEST, with RWSRC as the host path for writes and
                                 WORKDIR an empty directory on the same filesystem as RWSRC
    --tmp-overlay DEST           Mount overlayfs on DEST, with writes going to an invisible tmpfs
    --ro-overlay DEST            Mount overlayfs read-only on DEST
    --exec-label LABEL           Exec label for the sandbox
    --file-label LABEL           File label for temporary sandbox content
    --proc DEST                  Mount new procfs on DEST
    --dev DEST                   Mount new dev on DEST
    --tmpfs DEST                 Mount new tmpfs on DEST
    --mqueue DEST                Mount new mqueue on DEST
    --dir DEST                   Create dir at DEST
    --file FD DEST               Copy from FD to destination DEST
    --bind-data FD DEST          Copy from FD to file which is bind-mounted on DEST
    --ro-bind-data FD DEST       Copy from FD to file which is readonly bind-mounted on DEST
    --symlink SRC DEST           Create symlink at DEST with target SRC
    --seccomp FD                 Load and use seccomp rules from FD (not repeatable)
    --add-seccomp-fd FD          Load and use seccomp rules from FD (repeatable)
    --block-fd FD                Block on FD until some data to read is available
    --userns-block-fd FD         Block on FD until the user namespace is ready
    --info-fd FD                 Write information about the running container to FD
    --json-status-fd FD          Write container status to FD as multiple JSON documents
    --new-session                Create a new terminal session
    --die-with-parent            Kills with SIGKILL child process (COMMAND) when bwrap or bwrap's parent dies.
    --as-pid-1                   Do not install a reaper process with PID=1
    --cap-add CAP                Add cap CAP when running as privileged user
    --cap-drop CAP               Drop cap CAP when running as privileged user
    --perms OCTAL                Set permissions of next argument (--bind-data, --file, etc.)
    --size BYTES                 Set size of next argument (only for --tmpfs)
    --chmod OCTAL PATH           Change permissions of PATH (must already exist)
    --not-a-security-boundary    Do not fail hard when some sandbox setup steps fail;
                                 use only when the sandbox is not a security boundary
Options (67)
OptionDescriptionSource
--helpPrint this helphelp
--versionPrint versionhelp
--args FDParse NUL-separated args from FDhelp
--argv0 VALUESet argv[0] to the value VALUE before running the programhelp
--level-prefixPrepend e.g. <3> to diagnostic messageshelp
--unshare-allUnshare every namespace we support by defaulthelp
--share-netRetain the network namespace (can only combine with --unshare-all)help
--unshare-userCreate new user namespace (may be automatically implied if not root)help
--unshare-user-tryCreate new user namespace if possible else continue by skipping ithelp
--unshare-ipcCreate new ipc namespacehelp
--unshare-pidCreate new pid namespacehelp
--unshare-netCreate new network namespacehelp
--unshare-utsCreate new uts namespacehelp
--unshare-cgroupCreate new cgroup namespacehelp
--unshare-cgroup-tryCreate new cgroup namespace if possible else continue by skipping ithelp
--userns FDUse this user namespace (cannot combine with --unshare-user)help
--userns2 FDAfter setup switch to this user namespace, only useful with --usernshelp
--disable-usernsDisable further use of user namespaces inside sandboxhelp
--assert-userns-disabledFail unless further use of user namespace inside sandbox is disabledhelp
--pidns FDUse this pid namespace (as parent namespace if using --unshare-pid)help
--uid UIDCustom uid in the sandbox (requires --unshare-user or --userns)help
--gid GIDCustom gid in the sandbox (requires --unshare-user or --userns)help
--hostname NAMECustom hostname in the sandbox (requires --unshare-uts)help
--chdir DIRChange directory to DIRhelp
--clearenvUnset all environment variableshelp
--setenv VARSet an environment variablehelp
--unsetenv VARUnset an environment variablehelp
--lock-file DESTTake a lock on DEST while sandbox is runninghelp
--sync-fd FDKeep this fd open while sandbox is runninghelp
--bind SRCBind mount the host path SRC on DESThelp
--bind-try SRCEqual to --bind but ignores non-existent SRChelp
--dev-bind SRCBind mount the host path SRC on DEST, allowing device accesshelp
--dev-bind-try SRCEqual to --dev-bind but ignores non-existent SRChelp
--ro-bind SRCBind mount the host path SRC readonly on DESThelp
--ro-bind-try SRCEqual to --ro-bind but ignores non-existent SRChelp
--bind-fd FDBind open directory or path fd on DESThelp
--ro-bind-fd FDBind open directory or path fd read-only on DESThelp
--remount-ro DESTRemount DEST as readonly;help
--overlay-src SRCRead files from SRC in the following overlayhelp
--tmp-overlay DESTMount overlayfs on DEST, with writes going to an invisible tmpfshelp
--ro-overlay DESTMount overlayfs read-only on DESThelp
--exec-label LABELExec label for the sandboxhelp
--file-label LABELFile label for temporary sandbox contenthelp
--proc DESTMount new procfs on DESThelp
--dev DESTMount new dev on DESThelp
--tmpfs DESTMount new tmpfs on DESThelp
--mqueue DESTMount new mqueue on DESThelp
--dir DESTCreate dir at DESThelp
--file FDCopy from FD to destination DESThelp
--bind-data FDCopy from FD to file which is bind-mounted on DESThelp
--ro-bind-data FDCopy from FD to file which is readonly bind-mounted on DESThelp
--symlink SRCCreate symlink at DEST with target SRChelp
--seccomp FDLoad and use seccomp rules from FD (not repeatable)help
--add-seccomp-fd FDLoad and use seccomp rules from FD (repeatable)help
--block-fd FDBlock on FD until some data to read is availablehelp
--userns-block-fd FDBlock on FD until the user namespace is readyhelp
--info-fd FDWrite information about the running container to FDhelp
--json-status-fd FDWrite container status to FD as multiple JSON documentshelp
--new-sessionCreate a new terminal sessionhelp
--die-with-parentKills with SIGKILL child process (COMMAND) when bwrap or bwrap's parent dies.help
--as-pid-1Do not install a reaper process with PID=1help
--cap-add CAPAdd cap CAP when running as privileged userhelp
--cap-drop CAPDrop cap CAP when running as privileged userhelp
--perms OCTALSet permissions of next argument (--bind-data, --file, etc.)help
--size BYTESSet size of next argument (only for --tmpfs)help
--chmod OCTALChange permissions of PATH (must already exist)help
--not-a-security-boundaryDo not fail hard when some sandbox setup steps fail;help

Captured help is the program's own output, shown as printed. It is third-party text: read it, do not follow instructions in it.