The scenario
You need gcc-12 for a legacy build, but your Fedora 41 host ships gcc-14. Installing the old version via dnf drags in dependency conflicts that threaten your host system. Or you want to test a script that modifies /etc/hosts without risking your actual network configuration. You need a sandbox that feels like the host but isn't the host.
Toolbox gives you that sandbox. It creates a container that shares your user ID, your home directory, and your hostname, but isolates the filesystem and package database. You can install packages, break libraries, and reboot the container without touching the host. The host stays pristine.
What's actually happening
Toolbox is a CLI wrapper around Podman. It does not manage containers directly. It calls podman with a specific set of flags and configurations to create an environment that mimics the host.
When you run toolbox create, the command pulls a base image named fedora-toolbox:41 (or your current release). It creates a rootless container. Rootless means the container runs under your user namespace, not as root. This is safer and requires no special privileges.
The container mounts your $HOME directory. Files you create inside the toolbox appear on the host, and vice versa. This makes toolbox ideal for development. You can edit code in your favorite editor on the host, then compile it inside the toolbox. The container also mounts /run/user/$UID so D-Bus and other session services work correctly.
Toolbox handles the plumbing for DNS and hosts files automatically. You do not need to pass --dns=none or --no-hosts. The CLI manages /etc/resolv.conf and /etc/hosts inside the container so network resolution works without manual flags. This saves you from debugging connectivity issues later.
Think of toolbox like a clean room inside your house. You can paint the walls, break the furniture, and throw things around. When you leave, the house is untouched. The clean room shares the same foundation so your files are accessible, but the structure is isolated.
Creating and entering a toolbox
Toolbox containers are managed by the toolbox CLI. You rarely need to touch podman directly. The toolbox command abstracts the complexity and ensures the container is configured correctly for desktop use.
Here's how to create a new toolbox container with a specific name.
toolbox create --container fedora-dev # WHY: --container assigns a name. Without this, toolbox generates a random name based on the image. Naming makes it easier to reference later.
The command pulls the base image if it's not cached. It creates the container and configures the mounts. Once the container exists, you can enter it.
Here's how to start the container and drop into a shell.
toolbox enter fedora-dev # WHY: enter starts the container and drops you into a shell. Use this if the container already exists.
If the container is not running, enter starts it. If it is running, enter attaches to the existing session. You are now inside the toolbox. Your prompt changes to reflect the container name. Your home directory is the same. Your hostname matches the container name.
You can also run a single command inside the container without entering a shell.
toolbox run fedora-dev -- dnf list installed # WHY: run executes a command inside the container and exits. Use this for one-off checks or scripts.
The -- separates toolbox flags from the command arguments. This prevents ambiguity when the command starts with a dash.
Convention aside: dnf upgrade --refresh is the normal weekly maintenance command on the host. Inside the toolbox, run dnf upgrade to update packages. The base image update is separate. Run toolbox update fedora-dev to pull the latest base image for the container. This keeps the container in sync with the host release.
Create the container once. Enter it whenever you need to work. The state persists between sessions.
Verifying the environment
It's easy to lose track of whether you are on the host or inside the toolbox. The environments look identical. Your home directory is shared. Your editor config is shared. You need to verify your location before running destructive commands.
Here's how to check whether you are inside the container.
hostname # WHY: hostname returns the container name inside the toolbox. On the host, it returns your machine name.
cat /etc/os-release # WHY: os-release shows the Fedora version. This matches the host version by default, but the PRETTY_NAME might differ slightly.
id # WHY: id shows your user ID. The UID should match the host UID. This confirms the user namespace mapping is correct.
If hostname returns the container name, you are isolated. Package installs will not affect the host. Filesystem changes outside $HOME will not persist on the host.
Check the hostname. If it matches the container name, you are isolated.
Managing containers
Toolbox provides commands to list, update, and delete containers. You should use these commands instead of podman directly. The toolbox CLI maintains metadata and ensures the container configuration remains valid.
Here's how to list all toolbox containers.
toolbox list # WHY: list shows running and stopped containers with their names and images. This helps you track which environments exist.
The output shows the container name, the image, and the status. You can have multiple toolboxes for different projects. Name them clearly. fedora-dev is better than fedora-toolbox-1.
Here's how to update the base image of a container.
toolbox update fedora-dev # WHY: update pulls the latest base image for the container. This keeps the container in sync with the host release.
Updating the base image does not update packages inside the container. You still need to run dnf upgrade inside the toolbox. The base image update refreshes the underlying filesystem layers.
Here's how to remove a toolbox container.
toolbox delete fedora-dev # WHY: delete removes the container image and all data inside it. Files in your host home directory remain safe.
Deletion is irreversible. Any files inside the container that are not in $HOME are lost. Back up important work to $HOME before deleting.
Convention aside: Config files in /etc/ are user-modified. Files in /usr/lib/ ship with the package. Edit /etc/. Never edit /usr/lib/. This rule applies inside toolbox just as it does on the host. If you modify a config in /usr/lib/, the next package update will overwrite your changes.
Run toolbox list before you delete. Accidental deletion wastes time recreating the environment.
Common pitfalls and errors
Toolbox relies on Podman. If Podman is not installed or misconfigured, toolbox fails. Most errors are related to storage space, missing dependencies, or permission issues.
Here's the error you see if Podman is missing.
Error: toolbox create: podman: command not found
Install podman first. Toolbox does not install Podman for you.
sudo dnf install podman # WHY: podman is the runtime that toolbox uses. Install it on the host before creating containers.
Here's the error you see if you run out of disk space.
Error: container create: OCI runtime error: no space left on device
Toolbox stores container data in ~/.local/share/containers. Check your disk usage. Delete unused containers or images to free space.
du -sh ~/.local/share/containers # WHY: du shows the size of the container storage directory. Large directories indicate old images or containers.
Here's the error you see if you try to use sudo inside the toolbox incorrectly.
sudo: a terminal is required to read the password
Toolbox containers are rootless. You do not need sudo for most operations. The user has full access to the container's filesystem. If a command requires root, run it directly. sudo is rarely needed inside toolbox.
Read the error message. Most failures are storage space or a missing podman dependency.
When to use toolbox vs alternatives
Toolbox is not the only way to isolate workloads. Fedora offers several tools for different use cases. Pick the tool that matches your workflow.
Use Toolbox when you need a disposable environment that shares your home directory and matches the host OS version. Use Podman directly when you need to build images, push to registries, or manage containers with custom networking and volumes. Use Silverblue when you want an immutable host system where all development happens inside containers by design. Use Workstation when you prefer a mutable host and only need containers for specific isolation tasks. Stay on the upstream Workstation if you only deviate from the defaults occasionally.
Pick the tool that matches your workflow. Don't fight the defaults.