Codex bubblewrap errors on Linux: each warning and its fix

Which message you have

Codex checks three things at startup, in this order, and shows the first warning that applies. Fixing one can reveal the next: on Ubuntu 24.04, installing bubblewrap usually turns the PATH warning into the user namespaces one.

The warnings appear only when Codex is set to sandbox its commands, and the prerequisites in OpenAI’s sandboxing docs cover the same ground. Inside a running session the same problem shows as bwrap: lines in the output of every command Codex tries, and with approvals on, Codex asks to rerun each one outside the sandbox.

“Codex could not find bubblewrap on PATH”

The full message, from Codex’s source:

Codex could not find bubblewrap on PATH. Install bubblewrap with your
OS package manager. See the sandbox prerequisites:
https://developers.openai.com/codex/concepts/sandboxing#prerequisites.
Codex will use the bundled bubblewrap in the meantime.

Codex ships its own copy of bwrap and falls back to it, so the sandbox may still work. Install the distribution’s package anyway:

sudo apt install bubblewrap     # Ubuntu, Debian
sudo dnf install bubblewrap     # Fedora

The bundled copy needs the kernel to allow unprivileged user namespaces with no help, and on Ubuntu 24.04 the AppArmor profiles that grant them name /usr/bin/bwrap by path, so they never apply to it. Codex prefers the system binary whenever one is on PATH.

If command -v bwrap prints a path and Codex still says it found nothing, Codex rejected the one you have. It skips a candidate the sandboxed commands could themselves change, because a bwrap the agent can rewrite is no sandbox at all. The source rejects one that is:

• found through a relative PATH entry, such as .;
• inside the folder Codex was started in, unless that folder is /;
• in a place the sandbox lets commands write to, where you could edit the file or replace it.

A copy built from source into the project, or into a folder the sandbox has been given as writable, is the usual way to hit this. The package’s /usr/bin/bwrap, owned by root, passes.

command -v bwrap
ls -l "$(command -v bwrap)"
bwrap --version

“Codex’s Linux sandbox uses bubblewrap and needs access to create user namespaces”

This one comes from a test Codex runs before the first command. It starts the bwrap it found with:

bwrap --unshare-user --unshare-net --ro-bind / / /bin/true

and shows the warning only when that exits with an error and its error output contains one of four bubblewrap messages:

setting up uid map: Permission denied
loopback: Failed RTM_NEWADDR
loopback: Failed RTM_NEWLINK
No permissions to create a new namespace

Run the same command yourself, as the user Codex runs as. It prints nothing and exits 0 when the machine allows what the sandbox needs; anything else tells you which gate is shut. Two cautions from the same source: the test gives up after half a second and counts that as a pass, and so does a bwrap that cannot be started at all, so a missing warning is not proof the sandbox works. The check at the end of this page is.

Ubuntu 23.10 and later, 24.04 above all

Since 23.10, Ubuntu lets a program create unprivileged user namespaces only when an AppArmor profile allows it. This is on when the setting reads 1:

sysctl kernel.apparmor_restrict_unprivileged_userns

On a fresh 24.04 machine it does, and the test fails with the uid map or RTM_NEWADDR line. OpenAI’s fix loads the bwrap-userns-restrict profile, which ships with the apparmor-profiles package but is not enabled:

sudo apt update
sudo apt install bubblewrap apparmor-profiles apparmor-utils
sudo install -m 0644 \
  /usr/share/apparmor/extra-profiles/bwrap-userns-restrict \
  /etc/apparmor.d/bwrap-userns-restrict
sudo apparmor_parser -r /etc/apparmor.d/bwrap-userns-restrict

On Ubuntu 25.04, OpenAI’s docs say the package from Ubuntu’s repository works with no extra AppArmor step. Anthropic’s Claude Code docs give a shorter profile for the same binary, and on Ubuntu 24.04 it serves Codex as well; the Codex on a Linux server guide has it, and which of the two to load. OpenAI’s last resort switches the restriction off for every program until the next reboot, a wider change than either profile:

sudo sysctl -w kernel.apparmor_restrict_unprivileged_userns=0

Debian, hardened kernels and machines that turned namespaces off

Two other kernel settings refuse the namespace outright. Debian’s notes for its bubblewrap package describe both:

• kernel.unprivileged_userns_clone, a Debian setting. It defaults to 1 on Debian kernels 5.10 and newer and on Ubuntu’s, and to 0 on older Debian kernels. At 0 the kernel refuses with a permission error, bubblewrap says “No permissions to create a new namespace”, and Codex shows its warning.
• user.max_user_namespaces, the limit on how many user namespaces may exist. Debian’s notes call setting it to 0 the recommended way to turn them off. Past that limit the kernel answers “no space” (ENOSPC) rather than a permission error, so bubblewrap’s message is not one of the four Codex looks for: Codex may start with no warning, and every sandboxed command fails. The probe command above shows it.

sysctl kernel.unprivileged_userns_clone   # only on kernels with Debian's patch
sysctl user.max_user_namespaces           # 0 means none allowed

If you administer the machine and the setting was not chosen on purpose, raise it, for example sudo sysctl -w kernel.unprivileged_userns_clone=1, and write it to a file under /etc/sysctl.d/ to keep it after a reboot. If someone set it as policy, that is a decision for them; Debian’s notes say some kernel attacks are harder with it at 0. A third message, “Creating new namespace failed, likely because the kernel does not support user namespaces”, means the kernel was built without them, which no setting changes.

Inside a Docker container or a dev container

Docker’s default seccomp profile refuses unprivileged user namespaces: on Docker 29.7, unshare -U true inside a container under the default profile fails with “Operation not permitted”. Bubblewrap then fails before AppArmor is consulted, with lines like these from a dev container report on Codex’s tracker, where the container user was root:

bwrap: loopback: Failed to create NETLINK_ROUTE socket: Operation not permitted
bwrap: No permissions to create a new namespace

Being root inside the container is no way around it, as that report shows. There are two ways out. OpenAI’s security docs say that when the container is the boundary you intend, run Codex inside it with --sandbox danger-full-access, and give the container only the files, credentials and network you would give the agent. The other is to open the namespace gate for that container, which takes a seccomp profile allowing clone, unshare and setns and sometimes an AppArmor change as well; the guide to Chrome’s sandbox in Docker walks through both gates, which are the same ones.

“…which is not supported on WSL1”

The message in full:

Codex's Linux sandbox uses bubblewrap, which is not supported on WSL1
because WSL1 cannot create the required user namespaces. Use WSL2 for
sandboxed shell commands.

WSL1 has no Linux kernel to make the namespace, so no package or setting fixes it, and Codex refuses sandboxed commands there before calling bwrap. WSL2 follows the ordinary Linux path. From PowerShell, Microsoft’s commands show which version each distribution runs and convert one:

wsl -l -v
wsl --set-version Ubuntu 2

Microsoft warns that the conversion can take a while and can fail on large distributions, so back up the projects in it first. Then install bubblewrap inside the distribution as above. Codex in PowerShell, outside WSL, uses Windows’ own sandbox and none of this applies.

“Read-only file system” on .git is the sandbox working

A git commit that fails inside Codex’s sandbox with “Unable to create ‘.git/index.lock’: Read-only file system” is not a bubblewrap fault. OpenAI’s security docs list paths that stay read-only even in the workspace-write mode, inside a folder Codex may otherwise write: .git, and .agents and .codex when they are folders. With approvals on, Codex asks to run the commit outside the sandbox; otherwise you run it yourself. Likewise, a download that fails inside the sandbox is its network being off by default; the server guide has the setting that turns it on.

Check that the sandbox works

codex sandbox runs one command under the same policy Codex applies to its own, with no model involved. From inside a project:

cd ~/your-project
codex sandbox -- ls
codex sandbox -- touch ../outside.txt

The first should list the folder and the second should fail, because nothing outside the project is writable. A bwrap: line on either means the fix has not taken. Some posts, and OpenAI’s security docs as of October 2026, show codex sandbox linux …; current releases pick the platform themselves, so that form tries to run a program called linux.

When nothing on the machine can let bubblewrap make its namespace, the choice left is where the boundary sits. Running Codex with --sandbox danger-full-access on a laptop full of your keys hands every command the agent writes what you can reach; on a machine or container that holds only the work, it is the boundary OpenAI recommends. The guide to running without permission prompts weighs the modes, and securing a server for coding agents shows what the sandbox keeps from a command, and what it does not.