You need a mutable shell on an immutable desktop
You installed Fedora Silverblue because you want a system that never breaks. You love the atomic updates and the rollback capability. Then you try to install a niche development library, a proprietary driver, or a tool that only exists in a third-party repository. You run sudo dnf install and the terminal rejects you. The root filesystem is read-only. You cannot install packages directly to /usr.
You could use rpm-ostree install, but that requires a reboot for every package and adds weight to the system image. You need a mutable environment where dnf works instantly, but you don't want to compromise the stability of your host. Distrobox creates a mutable Fedora container that shares your home directory and display session. You get a full development environment without touching the host filesystem.
Install Distrobox. Get your mutable shell. Keep the host sealed.
How Distrobox bridges the gap
Silverblue uses rpm-ostree to manage the system. The base image is committed to disk and mounted read-only. Any change requires a transactional boot entry. This design prevents broken upgrades and allows instant rollback. It also means the host is not designed for ad-hoc package installation.
Distrobox uses Podman to run a container with a mutable Fedora image. The container runs as your user, not as root. Distrobox bind-mounts your home directory into the container. Your configuration files, dotfiles, and projects are accessible from both the host and the container. Distrobox also forwards your X11 or Wayland socket. GUI applications launched inside the container appear on your desktop as if they were native.
Think of the host as a sealed vault. The vault holds your critical system files and never changes except through controlled transactions. Distrobox is a workbench bolted to the side of the vault. You can hammer, saw, and spill coffee on the workbench. The vault stays pristine. When the workbench gets too messy, you tear it down and build a new one. The vault is unaffected.
The vault stays sealed. The workbench takes the abuse.
Install and create your container
Distrobox is available in the default Fedora repositories. On Silverblue, you must use rpm-ostree to install host packages. The command adds the package to the next boot entry. You must reboot for the installation to take effect.
Here's how to install Distrobox on the host system.
rpm-ostree install distrobox # Install distrobox via rpm-ostree for atomic desktops
# rpm-ostree adds the package to the new boot entry. The binary is not available yet.
# Reboot is required. Atomic systems apply changes on the next boot.
sudo reboot
After the reboot, create a container. The distrobox create command pulls a base image and sets up the environment. Use --name to assign an identifier. Use --image to specify the base. fedora:latest pulls the current Fedora release, which matches the host in most cases.
Here's how to create a new container named dev-box.
distrobox create --name dev-box --image fedora:latest # Create container with latest Fedora image
# --name sets the identifier. Use this name for enter, stop, and rm commands.
# --image pulls the base image. fedora:latest matches the host release usually.
# The command downloads the image layers if they are not cached locally.
Reboot after rpm-ostree install. The package won't exist until the new boot entry loads.
Enter and install tools
Once the container is created, enter it with distrobox enter. The command starts a shell inside the container. Your prompt usually changes to indicate you are in the container. The shell inherits your environment variables and aliases. You can run dnf without sudo because the container runs as your user.
Here's how to enter the container and install development tools.
distrobox enter dev-box # Enter the container shell
# You are now inside the mutable environment. The prompt usually changes.
# Home directory is shared. Your dotfiles are visible here.
dnf install gcc make cmake ripgrep # Install dev tools. No sudo needed inside container.
# Packages install to the container root. Host remains untouched.
# dnf works instantly. No reboot required.
Install inside the container. The host filesystem never sees the package.
Export binaries to the host
Distrobox includes a feature called distrobox-export. This command creates a wrapper script on the host that forwards execution to the container. You can export binaries, environment variables, or shell functions. The wrapper runs in the container but appears to run on the host. This lets you use tools installed in the container from your host shell without entering the container manually.
Here's how to export a binary so it runs from the host shell.
distrobox enter dev-box # Enter container to export
dnf install ripgrep # Ensure the tool is installed in the container
distrobox-export --bin rg # Export rg binary to host shell
# Creates a wrapper script in ~/.local/bin/rg on the host.
# The wrapper launches the container and runs rg inside it.
exit # Leave container to test on host
rg --version # Verify on host. Output comes from container version.
# The host shell runs the wrapper. The container executes the binary.
Export the binary. Run it from the host. The container stays hidden.
Verify the isolation
Verification is simple. Check that the tool exists inside the container and does not exist on the host. Use rpm-ostree status to confirm the host image is unchanged. The host should show no new packages. The container holds all the modifications.
Here's how to verify the tool is isolated to the container.
distrobox enter dev-box # Enter container
which gcc # Check path inside container. Should point to /usr/bin/gcc.
# gcc is installed in the container root.
exit # Return to host shell
which gcc # Check host. Should return nothing or a different path.
# gcc is not on the host. The host path is clean.
rpm-ostree status # Verify host state. No new packages listed.
# The deployed commit remains unchanged. Distrobox did not modify the host.
Check rpm-ostree status. If the host is clean, the container did its job.
Common errors and fixes
Distrobox relies on Podman and your display server. Errors usually stem from missing reboots, stopped services, or socket permissions.
If you see distrobox: command not found after installing, you forgot to reboot. rpm-ostree installs packages for the next boot. The binary does not exist in the current boot environment. Run sudo reboot.
If you see Error: cannot connect to Podman socket, the Podman service is not running. Podman runs as a user service on Silverblue. Start the service and enable it to start at login.
systemctl --user start podman # Start the user podman service
# Podman runs as a user service. Use --user flag for systemctl.
systemctl --user enable podman # Enable podman to start on login
# Ensures the socket is available when you open a terminal.
If you get permission denied when launching GUI apps, check your Wayland configuration. Distrobox forwards the Wayland socket automatically in most cases. Some desktop environments or custom setups block socket access. You can force XWayland forwarding with the --xephyr flag when creating the container, or use --nested for nested Wayland sessions.
If you see Error: container dev-box not found, you used the wrong name or the container was removed. List existing containers with distrobox list.
distrobox list # Show all containers and their states
# Lists name, image, and status. Helps identify typos or missing containers.
Check systemctl --user status podman. The container won't start if the runtime is down.
Maintenance and cleanup
Containers accumulate over time. Old containers consume disk space. Use distrobox upgrade-all to update all containers at once. This command runs dnf upgrade inside each container. It keeps your development environments current without entering each one manually.
When a container is no longer needed, remove it. Stop the container first, then remove it with distrobox rm. The removal deletes the container and its filesystem. Data in your home directory remains safe because it lives on the host.
Here's how to remove a container and reclaim space.
distrobox stop dev-box # Stop the container first
# Stopping ensures no processes are running. Prevents removal errors.
distrobox rm dev-box # Remove container and image
# --rm removes the container. Data inside the container root is lost.
# Home directory files are preserved. They live on the host.
Remove the container when done. Orphaned images eat disk space.
When to use Distrobox
Choose the right tool based on your scope and requirements. Each option has a specific role in the Fedora ecosystem.
Use Distrobox when you need a mutable environment with full dnf access on an immutable desktop.
Use Toolbox when you want a simpler, distro-matched container managed by the host OS with less configuration.
Use rpm-ostree install when you need the package available system-wide for all users and services.
Stay on the host shell when you only need tools already provided by the default Silverblue image.
Use a VM when you need hardware isolation or a completely different kernel.
Pick the tool that matches the scope. Containers for dev. rpm-ostree for system.