[Error] DBX_CONTAINER_HOME_PREFIX with relative path fails: "invalid container path, must be an absolute path"

[fungs]

Rationale / Problem description

I’m using Distrobox to create reproducible local dev environments and want each container to have its own separate home directory under my user’s $HOME, without hardcoding an absolute path that bakes in my username or home location.

DBX_CONTAINER_HOME_PREFIX looks like the right mechanism to achieve this: the docs and issues state that it defines where containers’ home directories will be located, and that a container named test will have its home set to $DBX_CONTAINER_HOME_PREFIX/test. Conceptually, for portability, it would be ideal if this prefix could be configured in a $HOME‑relative or otherwise portable way and not require a fully hardcoded absolute path.

However, using a relative path currently fails at runtime with an error from the underlying container runtime.

Steps to reproduce

Environment:

• Distrobox version: 1.8.2.4 (likely v2 also applies, but wasn't able to verify)
• Host: Fedora Atomic, Kernel 6.19.14-101.fc44.x86_64
• Backend: Podman (rootless)

Config:

mkdir -p ~/.config/distrobox
cat > ~/.config/distrobox/distrobox.conf << 'EOF'
DBX_CONTAINER_HOME_PREFIX=distrobox_homes
EOF

Then:

distrobox create --name test --image registry.fedoraproject.org/fedora:40

Actual behavior

Container creation fails with an error like:

Error: invalid container path "distrobox_homes", must be an absolute path

This indicates that DBX_CONTAINER_HOME_PREFIX is taken literally, concatenated with the container name, and passed directly to the backend as the value of --home, without any normalization or $HOME‑relative resolution. Because it is a relative path, Podman rejects it as invalid.

Expected / desired behavior

From a user’s point of view, there are two reasonable and portable semantics that would avoid this problem:

1. Either:

   • Define that DBX_CONTAINER_HOME_PREFIX must be absolute, and:
   • Provide a way to refer to the user’s home generically in distrobox.conf (e.g. ${HOME}, %h, or similar) that Distrobox itself expands before passing to the backend.

2. Or:

   • Define that if DBX_CONTAINER_HOME_PREFIX is a relative path, it is automatically interpreted as relative to the user’s $HOME (or another clearly documented base directory).
   • Distrobox would then internally compute an absolute path before calling Podman/Docker, avoiding the “must be absolute” error.

Right now, the behavior is:

• Relative prefixes are accepted in the config, but cause runtime errors when used.
• There is no documented placeholder for $HOME or “relative under home” semantics, which makes DBX_CONTAINER_HOME_PREFIX awkward to use in portable configs (dotfiles, shared repos, multi-user machines).

Proposed solutions

Any of the following would improve the situation:

1. Normalize relative prefixes under $HOME

   • On startup / container creation, if DBX_CONTAINER_HOME_PREFIX is set and does not start with /:
     • Rewrite it internally to "$HOME/$DBX_CONTAINER_HOME_PREFIX".
   • Then compute the final home as:
     • home_to_use="$DBX_CONTAINER_HOME_PREFIX/$container_name" (all absolute).
   • This preserves current “absolute prefix” behavior while making relative prefixes behave intuitively.

2. Introduce an explicit $HOME placeholder

   • Document that DBX_CONTAINER_HOME_PREFIX can contain a token like ${HOME} or %h, and Distrobox will expand it prior to use.

   • Example:

     DBX_CONTAINER_HOME_PREFIX=${HOME}/distrobox

   • Internally, Distrobox performs the variable expansion and passes an absolute path to the backend.

3. At minimum: validate and document

   Even if you don’t want to change semantics:

   • Explicitly document that DBX_CONTAINER_HOME_PREFIX must be an absolute path and that relative paths will not work.
   • Add an early validation step that detects a non‑absolute prefix (e.g. does not start with /) and exits with a clear, Distrobox‑specific error message instead of letting the container runtime error bubble up.
   • Suggest a pattern for portable configs (e.g. “generate distrobox.conf per user with $HOME expanded via a small shell script”).

Why this matters

For people using Distrobox for reproducible dev environments and checking configuration into version control, it is very desirable to avoid hardcoding /home/<username>/... paths in committed files. Having a well-defined, supported way to express container homes as “under my home” (without relying on one-off templating scripts) would make DBX_CONTAINER_HOME_PREFIX significantly more usable and portable across machines and user accounts.