What does Distrobox actually export?

After you export an application from a container, a new icon appears on the desktop and you can type its command directly in a terminal. But the program has not moved onto the host: exporting creates an entry point back into the original container. Understanding these three layers, the entry point, the execution environment, and the data, explains problems such as “the icon is there but the application will not open” or “a command with the same name runs the wrong version.”

Two kinds of entry point, one source container#

distrobox-export commonly exports two kinds of item: desktop entries and associated icons for GUI applications, and wrapper scripts for CLI tools. Clicking the icon or executing the script routes the invocation back into the source container. The package and most of its runtime dependencies remain inside the container. [1]

This article explains the details using the Distrobox 1.8.2.5 export script. The examples assume that Distrobox, the source container, and the target program are already ready; arch-dev is only an example container name. Every command identifies where to run it. Do not paste commands into the host and container indiscriminately.

Exporting does not turn the container into an isolated sandbox either. Distrobox shares many host resources to support desktop and development workflows. Which data an application can access depends on the actual mounts, home configuration, and permissions. A desktop entry that looks like a native application does not change these boundaries. [5]

Export a GUI application, then inspect the files actually generated#

First, enter the prepared container from the host:

# 宿主机
distrobox enter arch-dev

Inside the source container, confirm that the application is installed and has a valid Desktop Entry. You can export by application name or explicitly supply the absolute path to its desktop file; the name need not exactly match an executable name in PATH.

# 来源容器：按应用名导出，附带便于识别的标签
distrobox-export --app gedit --export-label "(Dev)"

# 或者改用实际的 desktop 文件路径；与上一种是二选一
distrobox-export --app /usr/share/applications/org.gnome.gedit.desktop

# 查看当前来源容器导出的应用
distrobox-export --list-apps

The label only helps people identify the source in the launcher; it does not create new data isolation for the application. When multiple containers export the same software, clear container names and labels reduce accidental selections. Still inspect the actual entry to confirm which container it enters.

What changes in the Desktop Entry#

This version generally generates a prefixed entry using “container name + original desktop filename.” For example, the source file org.example.Editor.desktop corresponds to a file prefixed with the source container’s name. Do not construct a guessed path from “application name plus container name”; find the actual file in the export output or listing.

The export script rewrites Exec so that the application launches through a command that enters the container, and handles extra arguments and desktop field codes. It also removes TryExec, which is unsuitable for direct verification by the host, and settings such as DBusActivatable=true that could bypass the intended Exec launch path. It handles icon references and copying as well. [2]

This explains why manually copying a container’s desktop file unchanged onto the host may not produce a working entry point: the host may not find the same command and icon, or may use a different launch mechanism. When troubleshooting, read Exec and Icon in the generated file rather than relying on the name displayed in the launcher.

# 宿主机：替换为实际导出的文件路径
sed -n '1,160p' /path/to/exported.desktop
desktop-file-validate /path/to/exported.desktop

# 会启动应用，用于验证这个入口
gio launch /path/to/exported.desktop

The relevant tools must be installed for these checks. Syntax validation can detect Desktop Entry format problems, but it cannot prove that the program inside the container will run. Launching through gio also tests the entry point; you still need to observe the application’s result. update-desktop-database mainly maintains the MIME association cache. It is not a universal “force icon refresh” button for all desktop launchers.

Distinguish arguments for the application from arguments for entering the container#

For example, if the installed vim supports opening files in tabs, you can put -p in the application arguments. The following still runs inside the source container, and the destination directory must exist.

distrobox-export --bin /usr/bin/vim \
  --export-path "$HOME/.local/bin" \
  --extra-flags "-p"

In the script version pinned for this article, repeating --extra-flags replaces the previous value rather than appending to it. Combine multiple arguments into one value in the form the option accepts, then inspect the final output. Whether an option is supported depends on the application itself; launch settings that work for one Electron application do not imply that every application needs the same arguments. [2]

This version’s export operations cover applications, binaries, and listings. It does not provide --service to export systemd services. If you need to manage services across environments, design their lifecycle separately rather than using a nonexistent option.

After exporting a CLI tool, verify it with the full path first#

The following assumes that the container uses the default shared home and that $HOME/.local/bin already exists. Inside the source container, export jq using its actual absolute path:

# 来源容器
distrobox-export --bin /usr/bin/jq --export-path "$HOME/.local/bin"
distrobox-export --list-binaries --export-path "$HOME/.local/bin"

Back on the host, explicitly execute the generated wrapper script first, then check what resolves when no path is given:

# 宿主机
"$HOME/.local/bin/jq" --version
command -v jq
type -a jq
sed -n '1,120p' "$HOME/.local/bin/jq"

A full path eliminates interference from PATH lookup order. If jq is also installed on the host, typing jq may still run the host version, or it may find the wrapper first. This depends on the actual PATH, aliases, and other environment settings; exporting does not necessarily override the host command. Reading the wrapper also confirms the source container and how arguments are forwarded.

When exporting tools with the same name from multiple containers, plan separate destination subdirectories first, then decide whether and how to add them to PATH. This makes the source explicit and avoids a later export replacing a wrapper at the same path.

The wrapper chooses an execution route based on its environment#

The scripts generated by this version use CONTAINER_ID to distinguish invocation environments. On the host, they enter the source container. When invoked from another container, they first return to the host through host-exec, then enter the source container. When already inside the source container, they call the target program directly. [2]

This describes the official generation logic; it is not a recommendation to handwrite a one-line replacement wrapper. The real script also handles arguments, entry methods, and other details. If behavior is unexpected, inspecting the currently generated file is more reliable than comparing tutorial pseudocode with guesses about the local system.

A shared home changes how to reason about data paths#

With the default shared home, applications may read and write the very same configuration and documents as the host. This is convenient, but it also means different program versions in two containers may access the same state. “In different containers” does not automatically mean “using different application configurations.” [4]

If you create a container with a custom home, you should not assume that ~ inside it is the host’s home. Pay particular attention to the export directory: for a script intended to be on the host’s PATH, its apparent path inside the container is not enough to establish its location. First, you can read the host-home information supplied by Distrobox:

# 来源容器：只查看路径，再据实际挂载确定导出位置
printf '%s\n' "$DISTROBOX_HOST_HOME"

When further diagnosing missing files, ask all three questions: which environment resolves the path, is the supplied path absolute or relative, and is the file visible in that environment? An exported entry point connects the launch process; it does not synchronize all program data into a new directory tree.

If it will not open, test the entry point and program separately#

If you suspect a problem with an exported GUI entry point, enter the container directly from the host and launch the same application while observing terminal output. This starts the program; it is not a read-only query. Use the actual container and program names.

# 宿主机
distrobox enter arch-dev -- gedit

If direct launch also fails, fix the program or container-integration problem first. If direct launch succeeds but the exported entry fails, compare the arguments and environment passed by the generated entry. distrobox enter is the layer that enters the source environment; application errors require further diagnosis from the application’s own logs. [3]

Remove entry points separately from uninstalling applications#

To remove an export, return to the original source container and use the original application or binary path. If the CLI export used a custom directory, supply the same export-path as well.

# 原来源容器；各行对应各自的导出对象
distrobox-export --app gedit --delete
distrobox-export --bin /usr/bin/jq \
  --export-path "$HOME/.local/bin" \
  --delete

Confirm the target in the listing before performing the corresponding removal. GUI cleanup also involves desktop files and icons. The script has logic for handling entries under the original filename, so check first if a host entry has the same name; there is no guarantee that it will never affect any same-named file. [2]

Removing an entry point is not the same as uninstalling software inside the container, deleting the container, or deleting personal data. Before removing a container, you can clean up its exported entry points. If leftovers appear afterward, verify their source individually before removing them. Tracking entry-point lifecycles separately keeps stale pointers from gradually accumulating on the host desktop and in PATH.