'\" t
.\
.\"
.\" Define V font for inline verbatim, using C font in formats
.\" that render this, and otherwise B font.
.ie "\f[CB]x\f[]"x" \{\
. ftr V B
. ftr VI BI
. ftr VB B
. ftr VBI BI
.\}
.el \{\
. ftr V CR
. ftr VI CI
. ftr VB CB
. ftr VBI CBI
.\}
.TH "DISTROBOX-ASSEMBLE" "1" "May 2024" "Distrobox" "User Manual"
.hy
.SH NAME
.IP
.nf
\f[C]
distrobox assemble
distrobox-assemble
\f[R]
.fi
.SH DESCRIPTION
.PP
distrobox-assemble takes care of creating or destroying containers in
batches, based on a manifest file.
The manifest file by default is \f[V]./distrobox.ini\f[R], but can be
specified using the \f[V]--file\f[R] flag.
.SH SYNOPSIS
.PP
\f[B]distrobox assemble\f[R]
.IP
.nf
\f[C]
--file:         path to the distrobox manifest/ini file
--name/-n:      run against a single entry in the manifest/ini file
--replace/-R:       replace already existing distroboxes with matching names
--dry-run/-d:       only print the container manager command generated
--verbose/-v:       show more verbosity
--version/-V:       show version
\f[R]
.fi
.SH EXAMPLES
.PP
This is an example manifest file to create two containers:
.IP
.nf
\f[C]
[ubuntu]
additional_packages=\[dq]git vim tmux nodejs\[dq]
image=ubuntu:latest
init=false
nvidia=false
pull=true
root=false
replace=true
start_now=false

# You can add comments using this #
[arch] # also inline comments are supported
additional_packages=\[dq]git vim tmux nodejs\[dq]
home=/tmp/home
image=archlinux:latest
init=false
start_now=true
init_hooks=\[dq]touch /init-normal\[dq]
nvidia=true
pre_init_hooks=\[dq]touch /pre-init\[dq]
pull=true
root=false
replace=false
volume=\[dq]/tmp/test:/run/a /tmp/test:/run/b\[dq]
\f[R]
.fi
.PP
\f[B]Create\f[R]
.PP
We can bring them up simply using
.IP
.nf
\f[C]
distrobox assemble create
\f[R]
.fi
.PP
If the file is called \f[V]distrobox.ini\f[R] and is in the same
directory you\[cq]re launching the command, no further arguments are
needed.
You can specify a custom path for the file using
.IP
.nf
\f[C]
distrobox assemble create --file /my/custom/path.ini
\f[R]
.fi
.PP
\f[B]Replace\f[R]
.PP
By default, \f[V]distrobox assemble\f[R] will replace a container only
if \f[V]replace=true\f[R] is specified in the manifest file.
.PP
In the example of the manifest above, the ubuntu container will always
be replaced when running \f[V]distrobox assemble create\f[R], while the
arch container will not.
.PP
To force a replace for all containers in a manifest use the
\f[V]--replace\f[R] flag
.IP
.nf
\f[C]
distrobox assemble create --replace [--file my/custom/path.ini]
\f[R]
.fi
.PP
\f[B]Remove\f[R]
.PP
We can bring down all the containers in a manifest file by simply doing
.IP
.nf
\f[C]
distrobox assemble rm
\f[R]
.fi
.PP
Or using a custom path for the ini file
.IP
.nf
\f[C]
distrobox assemble rm --file my/custom/path.ini
\f[R]
.fi
.PP
\f[B]Test\f[R]
.PP
You can always test what distrobox \f[B]would do\f[R] by using the
\f[V]--dry-run\f[R] flag.
This command will only print what commands distrobox would do without
actually running them.
.PP
\f[B]Available options\f[R]
.PP
This is a list of available options with the corresponding type:
.PP
.TS
tab(@);
l l.
T{
Flag Name
T}@T{
Type
T}
_
T{
additional_flags
T}@T{
string
T}
T{
additional_packages
T}@T{
string
T}
T{
home
T}@T{
string
T}
T{
image
T}@T{
string
T}
T{
init_hooks
T}@T{
string
T}
T{
pre_init_hooks
T}@T{
string
T}
T{
volume
T}@T{
string
T}
T{
exported_apps
T}@T{
string
T}
T{
exported_bins
T}@T{
string
T}
T{
exported_bins_path
T}@T{
string
T}
T{
entry
T}@T{
bool
T}
T{
start_now
T}@T{
bool
T}
T{
init
T}@T{
bool
T}
T{
nvidia
T}@T{
bool
T}
T{
pull
T}@T{
bool
T}
T{
root
T}@T{
bool
T}
T{
unshare_ipc
T}@T{
bool
T}
T{
unshare_netns
T}@T{
bool
T}
T{
unshare_process
T}@T{
bool
T}
T{
unshare_devsys
T}@T{
bool
T}
T{
unshare_all
T}@T{
bool
T}
.TE
.PP
boolean options default to false if not specified.
string options can be broken in multiple declarations additively in
order to improve readability of the file:
.IP
.nf
\f[C]
[ubuntu]
image=ubuntu:latest
additional_packages=\[dq]git vim tmux nodejs\[dq]
additional_packages=\[dq]htop iftop iotop\[dq]
additional_packages=\[dq]zsh fish\[dq]
\f[R]
.fi
.PP
Be aware that if you\[cq]re doing lines with spaces, you need to quote
them.
If you\[cq]re doing multiple hooks (init or pre_init) in multiple lines,
end the line with a semicolon (;) in order to execute them one after the
other.
.PP
For an explanation of each of the option in the list, take a look at the
distrobox create usage, each option corresponds to one of the
\f[V]create\f[R] flags.
.PP
\f[B]Advanced example\f[R]
.IP
.nf
\f[C]
[tumbleweed_distrobox]
image=registry.opensuse.org/opensuse/distrobox
pull=true
additional_packages=\[dq]acpi bash-completion findutils iproute iputils sensors inotify-tools unzip\[dq]
additional_packages=\[dq]net-tools nmap openssl procps psmisc rsync man tig tmux tree vim htop xclip yt-dlp\[dq]
additional_packages=\[dq]git git-credential-libsecret\[dq]
additional_packages=\[dq]patterns-devel-base-devel_basis\[dq]
additional_packages=\[dq]ShellCheck ansible-lint clang clang-tools codespell ctags desktop-file-utils gcc golang jq python3\[dq]
additional_packages=\[dq]python3-bashate python3-flake8 python3-mypy python3-pipx python3-pycodestyle python3-pyflakes python3-pylint python3-python-lsp-server python3-rstcheck python3-yapf python3-yamllint rustup shfmt\[dq]
additional_packages=\[dq]kubernetes-client helm\[dq]
init_hooks=GOPATH=\[dq]${HOME}/.local/share/system-go\[dq] GOBIN=/usr/local/bin go install github.com/golangci/golangci-lint/cmd/golangci-lint\[at]latest;
init_hooks=GOPATH=\[dq]${HOME}/.local/share/system-go\[dq] GOBIN=/usr/local/bin go install github.com/onsi/ginkgo/v2/ginkgo\[at]latest;
init_hooks=GOPATH=\[dq]${HOME}/.local/share/system-go\[dq] GOBIN=/usr/local/bin go install golang.org/x/tools/cmd/goimports\[at]latest;
init_hooks=GOPATH=\[dq]${HOME}/.local/share/system-go\[dq] GOBIN=/usr/local/bin go install golang.org/x/tools/gopls\[at]latest;
init_hooks=GOPATH=\[dq]${HOME}/.local/share/system-go\[dq] GOBIN=/usr/local/bin go install sigs.k8s.io/kind\[at]latest;
init_hooks=ln -sf /usr/bin/distrobox-host-exec /usr/local/bin/conmon;
init_hooks=ln -sf /usr/bin/distrobox-host-exec /usr/local/bin/crun;
init_hooks=ln -sf /usr/bin/distrobox-host-exec /usr/local/bin/docker;
init_hooks=ln -sf /usr/bin/distrobox-host-exec /usr/local/bin/docker-compose;
init_hooks=ln -sf /usr/bin/distrobox-host-exec /usr/local/bin/flatpak;
init_hooks=ln -sf /usr/bin/distrobox-host-exec /usr/local/bin/podman;
init_hooks=ln -sf /usr/bin/distrobox-host-exec /usr/local/bin/xdg-open;
exported_apps=\[dq]htop\[dq]
exported_bins=\[dq]/usr/bin/htop /usr/bin/git\[dq]
exported_bins_path=\[dq]\[ti]/.local/bin\[dq]
\f[R]
.fi
'\" t
.\
.\"
.\" Define V font for inline verbatim, using C font in formats
.\" that render this, and otherwise B font.
.ie "\f[CB]x\f[]"x" \{\
. ftr V B
. ftr VI BI
. ftr VB B
. ftr VBI BI
.\}
.el \{\
. ftr V CR
. ftr VI CI
. ftr VB CB
. ftr VBI CBI
.\}
.TH "DISTROBOX" "1" "May 2024" "Distrobox" "User Manual"
.hy
.SH COMPATIBILITY
.PP
This project \f[B]does not need a dedicated image\f[R].
It can use any OCI images from docker-hub, quay.io, or any registry of
your choice.
.PP
Many cloud images are stripped down on purpose to save size and may not
include commands such as \f[V]which\f[R], \f[V]mount\f[R],
\f[V]less\f[R] or \f[V]vi\f[R]).
Additional packages can be installed once inside the container.
We recommend using your preferred automation tool inside the container
if you find yourself having to repeatedly create new containers.
Maintaining your own custom image is also an option.
.PP
The main concern is having basic Linux utilities (\f[V]mount\f[R]),
basic user management utilities (\f[V]usermod, passwd\f[R]), and
\f[V]sudo\f[R] correctly set.
.SS SUPPORTED CONTAINER MANAGERS
.PP
\f[V]distrobox\f[R] can run on either \f[V]podman\f[R], \f[V]docker\f[R]
or \f[V]lilipod\f[R] (https://github.com/89luca89/lilipod)
.PP
It depends either on \f[V]podman\f[R] configured in
\f[V]rootless mode\f[R] or on \f[V]docker\f[R] configured without sudo
(follow THESE
instructions (https://docs.docker.com/engine/install/linux-postinstall/))
.IP \[bu] 2
Minimum podman version: \f[B]2.1.0\f[R]
.IP \[bu] 2
Minimum docker client version: \f[B]19.03.15\f[R]
.IP \[bu] 2
Minimum lilipod version: \f[B]v0.0.1\f[R]
.PP
Follow the official installation guide here:
.IP \[bu] 2
<https://podman.io/getting-started/installation>
.IP \[bu] 2
<https://docs.docker.com/engine/install>
.IP \[bu] 2
<https://docs.docker.com/engine/install/linux-postinstall/>
.SS CONTAINERS DISTROS
.PP
Distrobox guests tested successfully with the following container
images:
.PP
.TS
tab(@);
lw(23.3n) lw(23.3n) lw(23.3n).
T{
Distro
T}@T{
Version
T}@T{
Images
T}
_
T{
AlmaLinux (Toolbox)
T}@T{
8 9
T}@T{
quay.io/toolbx-images/almalinux-toolbox:8
quay.io/toolbx-images/almalinux-toolbox:9
quay.io/toolbx-images/almalinux-toolbox:latest
T}
T{
Alpine (Toolbox)
T}@T{
3.16 3.17 3.18 3.19 edge
T}@T{
quay.io/toolbx-images/alpine-toolbox:3.16
quay.io/toolbx-images/alpine-toolbox:3.17
quay.io/toolbx-images/alpine-toolbox:3.18
quay.io/toolbx-images/alpine-toolbox:3.19
quay.io/toolbx-images/alpine-toolbox:edge
quay.io/toolbx-images/alpine-toolbox:latest
T}
T{
AmazonLinux (Toolbox)
T}@T{
2 2022
T}@T{
quay.io/toolbx-images/amazonlinux-toolbox:2
quay.io/toolbx-images/amazonlinux-toolbox:2023
quay.io/toolbx-images/amazonlinux-toolbox:latest
T}
T{
Archlinux (Toolbox)
T}@T{
T}@T{
quay.io/toolbx/arch-toolbox:latest
T}
T{
Bazzite Arch
T}@T{
T}@T{
ghcr.io/ublue-os/bazzite-arch:latest
ghcr.io/ublue-os/bazzite-arch-gnome:latest
T}
T{
Centos (Toolbox)
T}@T{
stream8 stream9
T}@T{
quay.io/toolbx-images/centos-toolbox:stream8
quay.io/toolbx-images/centos-toolbox:stream9
quay.io/toolbx-images/centos-toolbox:latest
T}
T{
Debian (Toolbox)
T}@T{
10 11 12 testing unstable
T}@T{
quay.io/toolbx-images/debian-toolbox:10
quay.io/toolbx-images/debian-toolbox:11
quay.io/toolbx-images/debian-toolbox:12
quay.io/toolbx-images/debian-toolbox:testing
quay.io/toolbx-images/debian-toolbox:unstable
quay.io/toolbx-images/debian-toolbox:latest
T}
T{
Fedora (Toolbox)
T}@T{
37 38 39 Rawhide
T}@T{
registry.fedoraproject.org/fedora-toolbox:37
registry.fedoraproject.org/fedora-toolbox:38
registry.fedoraproject.org/fedora-toolbox:39
registry.fedoraproject.org/fedora-toolbox:rawhide
T}
T{
openSUSE (Toolbox)
T}@T{
T}@T{
registry.opensuse.org/opensuse/distrobox:latest
T}
T{
RedHat (Toolbox)
T}@T{
8 9
T}@T{
registry.access.redhat.com/ubi8/toolbox
registry.access.redhat.com/ubi9/toolbox
quay.io/toolbx-images/rhel-toolbox:latest
T}
T{
Rocky Linux (Toolbox)
T}@T{
8 9
T}@T{
quay.io/toolbx-images/rockylinux-toolbox:8
quay.io/toolbx-images/rockylinux-toolbox:9
quay.io/toolbx-images/rockylinux-toolbox:latest
T}
T{
Ubuntu (Toolbox)
T}@T{
16.04 18.04 20.04 22.04
T}@T{
quay.io/toolbx/ubuntu-toolbox:16.04 quay.io/toolbx/ubuntu-toolbox:18.04
quay.io/toolbx/ubuntu-toolbox:20.04 quay.io/toolbx/ubuntu-toolbox:22.04
quay.io/toolbx/ubuntu-toolbox:latest
T}
T{
T}@T{
T}@T{
T}
T{
AlmaLinux
T}@T{
8 8-minimal 9 9-minimal
T}@T{
docker.io/library/almalinux:8 docker.io/library/almalinux:9
T}
T{
Alpine Linux
T}@T{
3.15 3.16 3.17 3.18 3.19 edge
T}@T{
docker.io/library/alpine:3.15 docker.io/library/alpine:3.16
docker.io/library/alpine:3.17 docker.io/library/alpine:3.18
docker.io/library/alpine:3.19 docker.io/library/alpine:edge
docker.io/library/alpine:latest
T}
T{
AmazonLinux
T}@T{
1 2 2023
T}@T{
public.ecr.aws/amazonlinux/amazonlinux:1
public.ecr.aws/amazonlinux/amazonlinux:2
public.ecr.aws/amazonlinux/amazonlinux:2023
T}
T{
Archlinux
T}@T{
T}@T{
docker.io/library/archlinux:latest
T}
T{
CentOS Stream
T}@T{
8 9
T}@T{
quay.io/centos/centos:stream8 quay.io/centos/centos:stream9
T}
T{
CentOS
T}@T{
7
T}@T{
quay.io/centos/centos:7
T}
T{
Chainguard Wolfi
T}@T{
Small note: sudo is missing, use su-exec instead.
T}@T{
cgr.dev/chainguard/wolfi-base:latest
T}
T{
ClearLinux
T}@T{
T}@T{
docker.io/library/clearlinux:latest docker.io/library/clearlinux:base
T}
T{
Crystal Linux
T}@T{
T}@T{
registry.getcryst.al/crystal/misc/docker:latest
T}
T{
Debian
T}@T{
7 8 9 10 11 12
T}@T{
docker.io/debian/eol:wheezy docker.io/library/debian:buster
docker.io/library/debian:bullseye-backports
docker.io/library/debian:bookworm-backports
docker.io/library/debian:stable-backports
T}
T{
Debian
T}@T{
Testing
T}@T{
docker.io/library/debian:testing
docker.io/library/debian:testing-backports
T}
T{
Debian
T}@T{
Unstable
T}@T{
docker.io/library/debian:unstable
T}
T{
deepin
T}@T{
20 (apricot) 23 (beige)
T}@T{
docker.io/linuxdeepin/apricot
T}
T{
Fedora
T}@T{
36 37 38 39 Rawhide
T}@T{
quay.io/fedora/fedora:36 quay.io/fedora/fedora:37
quay.io/fedora/fedora:38 quay.io/fedora/fedora:39
quay.io/fedora/fedora:rawhide
T}
T{
Gentoo Linux
T}@T{
rolling
T}@T{
docker.io/gentoo/stage3:latest
T}
T{
KDE neon
T}@T{
Latest
T}@T{
invent-registry.kde.org/neon/docker-images/plasma:latest
T}
T{
Kali Linux
T}@T{
rolling
T}@T{
docker.io/kalilinux/kali-rolling:latest
T}
T{
Mint
T}@T{
21.1
T}@T{
docker.io/linuxmintd/mint21.1-amd64
T}
T{
Neurodebian
T}@T{
nd100
T}@T{
docker.io/library/neurodebian:nd100
T}
T{
openSUSE
T}@T{
Leap
T}@T{
registry.opensuse.org/opensuse/leap:latest
T}
T{
openSUSE
T}@T{
Tumbleweed
T}@T{
registry.opensuse.org/opensuse/distrobox:latest
registry.opensuse.org/opensuse/tumbleweed:latest
registry.opensuse.org/opensuse/toolbox:latest
T}
T{
Oracle Linux
T}@T{
7 7-slim 8 8-slim 9 9-slim
T}@T{
container-registry.oracle.com/os/oraclelinux:7
container-registry.oracle.com/os/oraclelinux:7-slim
container-registry.oracle.com/os/oraclelinux:8
container-registry.oracle.com/os/oraclelinux:8-slim
container-registry.oracle.com/os/oraclelinux:9
container-registry.oracle.com/os/oraclelinux:9-slim
T}
T{
RedHat (UBI)
T}@T{
7 8 9
T}@T{
registry.access.redhat.com/ubi7/ubi registry.access.redhat.com/ubi8/ubi
registry.access.redhat.com/ubi8/ubi-init
registry.access.redhat.com/ubi8/ubi-minimal
registry.access.redhat.com/ubi9/ubi
registry.access.redhat.com/ubi9/ubi-init
registry.access.redhat.com/ubi9/ubi-minimal
T}
T{
Rocky Linux
T}@T{
8 8-minimal 9
T}@T{
quay.io/rockylinux/rockylinux:8 quay.io/rockylinux/rockylinux:8-minimal
quay.io/rockylinux/rockylinux:9 quay.io/rockylinux/rockylinux:latest
T}
T{
Scientific Linux
T}@T{
7
T}@T{
docker.io/library/sl:7
T}
T{
Slackware
T}@T{
T}@T{
docker.io/vbatts/slackware:current
T}
T{
SteamOS
T}@T{
T}@T{
ghcr.io/linuxserver/steamos:latest
T}
T{
Ubuntu
T}@T{
14.04 16.04 18.04 20.04 22.04 23.04
T}@T{
docker.io/library/ubuntu:14.04 docker.io/library/ubuntu:16.04
docker.io/library/ubuntu:18.04 docker.io/library/ubuntu:20.04
docker.io/library/ubuntu:22.04
T}
T{
Vanilla OS
T}@T{
VSO
T}@T{
ghcr.io/vanilla-os/vso:main
T}
T{
Void Linux
T}@T{
glibc musl
T}@T{
ghcr.io/void-linux/void-glibc-full:latest
ghcr.io/void-linux/void-musl-full:latest
T}
.TE
.PP
Images marked with \f[B]Toolbox\f[R] are tailored images made by the
community efforts in
toolbx-images/images (https://github.com/toolbx-images/images), so they
are more indicated for desktop use, and first setup will take less time.
Note however that if you use a non-toolbox preconfigured image, the
\f[B]first\f[R] \f[V]distrobox-enter\f[R] you\[cq]ll perform can take a
while as it will download and install the missing dependencies.
.PP
A small time tax to pay for the ability to use any type of image.
This will \f[B]not\f[R] occur after the first time, \f[B]subsequent
enters will be much faster.\f[R]
.PP
NixOS is not a supported container distro, and there are currently no
plans to bring support to it.
If you are looking for unprivileged NixOS environments, we suggest you
look into
nix-shell (https://nixos.org/manual/nix/unstable/command-ref/nix-shell.html)
or nix portable (https://github.com/DavHau/nix-portable)
.SS NEW DISTRO SUPPORT
.PP
If your distro of choice is not on the list, open an issue requesting
support for it, we can work together to check if it is possible to add
support for it.
.PP
Or just try using it anyway, if it works, open an issue and it will be
added to the list!
.SS OLDER DISTRIBUTIONS
.PP
For older distributions like CentOS 5, CentOS 6, Debian 6, Ubuntu 12.04,
compatibility is not assured.
.PP
Their \f[V]libc\f[R] version is incompatible with kernel releases after
\f[V]>=4.11\f[R].
A work around this is to use the \f[V]vsyscall=emulate\f[R] flag in the
bootloader of the host.
.PP
Keep also in mind that mirrors could be down for such old releases, so
you will need to build a custom distrobox image to ensure basic
dependencies are met.
.SS GPU ACCELERATION SUPPORT
.PP
For Intel and AMD Gpus, the support is baked in, as the containers will
install their latest available mesa/dri drivers.
.PP
For NVidia, you can use the \f[V]--nvidia\f[R] flag during create, see
distrobox-create documentation to discover how to use it.
.PP
Alternatively, you can use the nvidia-container-toolkit utility to set
up the integration independently from the distrobox\[cq]s own flag.
.\
.\"
.\" Define V font for inline verbatim, using C font in formats
.\" that render this, and otherwise B font.
.ie "\f[CB]x\f[]"x" \{\
. ftr V B
. ftr VI BI
. ftr VB B
. ftr VBI BI
.\}
.el \{\
. ftr V CR
. ftr VI CI
. ftr VB CB
. ftr VBI CBI
.\}
.TH "DISTROBOX-CREATE" "1" "May 2024" "Distrobox" "User Manual"
.hy
.SH NAME
.IP
.nf
\f[C]
distrobox create
distrobox-create
\f[R]
.fi
.SH DESCRIPTION
.PP
distrobox-create takes care of creating the container with input name
and image.
The created container will be tightly integrated with the host, allowing
sharing of the HOME directory of the user, external storage, external
usb devices and graphical apps (X11/Wayland), and audio.
.SH SYNOPSIS
.PP
\f[B]distrobox create\f[R]
.IP
.nf
\f[C]
--image/-i:     image to use for the container  default: ${container_image_default}
--name/-n:      name for the distrobox          default: ${container_name_default}
--hostname:     hostname for the distrobox      default: <container-name>.$(uname -n)
--pull/-p:      pull the image even if it exists locally (implies --yes)
--yes/-Y:       non-interactive, pull images without asking
--root/-r:      launch podman/docker/lilipod with root privileges. Note that if you need root this is the preferred
            way over \[dq]sudo distrobox\[dq] (note: if using a program other than \[aq]sudo\[aq] for root privileges is necessary,
            specify it through the DBX_SUDO_PROGRAM env variable, or \[aq]distrobox_sudo_program\[aq] config variable)
--clone/-c:     name of the distrobox container to use as base for a new container
            this will be useful to either rename an existing distrobox or have multiple copies
            of the same environment.
--home/-H:      select a custom HOME directory for the container. Useful to avoid host\[aq]s home littering with temp files.
--volume:       additional volumes to add to the container
--additional-flags/-a:  additional flags to pass to the container manager command
--additional-packages/-ap:  additional packages to install during initial container setup
--init-hooks:       additional commands to execute during container initialization
--pre-init-hooks:   additional commands to execute prior to container initialization
--init/-I:      use init system (like systemd) inside the container.
            this will make host\[aq]s processes not visible from within the container. (assumes --unshare-process)
            may require additional packages depending on the container image: https://github.com/89luca89/distrobox/blob/main/docs/useful_tips.md#using-init-system-inside-a-distrobox
--nvidia:       try to integrate host\[aq]s nVidia drivers in the guest
--unshare-devsys:          do not share host devices and sysfs dirs from host
--unshare-groups:          do not forward user\[aq]s additional groups into the container
--unshare-ipc:          do not share ipc namespace with host
--unshare-netns:        do not share the net namespace with host
--unshare-process:          do not share process namespace with host
--unshare-all:          activate all the unshare flags below
--compatibility/-C: show list of compatible images
--help/-h:      show this message
--no-entry:     do not generate a container entry in the application list
--dry-run/-d:       only print the container manager command generated
--verbose/-v:       show more verbosity
--version/-V:       show version

--absolutely-disable-root-password-i-am-really-positively-sure: \[u26A0]\[uFE0F] \[u26A0]\[uFE0F]  when setting up a rootful distrobox, this will skip user password setup, leaving it blank. \[u26A0]\[uFE0F] \[u26A0]\[uFE0F]
\f[R]
.fi
.SH COMPATIBILITY
.IP
.nf
\f[C]
for a list of compatible images and container managers, please consult the man page:
    man distrobox
    man distrobox-compatibility
or consult the documentation page on: https://github.com/89luca89/distrobox/blob/main/docs/compatibility.md#containers-distros
\f[R]
.fi
.SH EXAMPLES
.PP
Create a distrobox with image alpine, called my-alpine container
.IP
.nf
\f[C]
distrobox create --image alpine my-alpine-container
\f[R]
.fi
.PP
Create a distrobox from fedora-toolbox:35 image
.IP
.nf
\f[C]
distrobox create --image registry.fedoraproject.org/fedora-toolbox:35 --name fedora-toolbox-35
\f[R]
.fi
.PP
Clone an existing distrobox container
.IP
.nf
\f[C]
distrobox create --clone fedora-35 --name fedora-35-copy
\f[R]
.fi
.PP
Always pull for the new image when creating a distrobox
.IP
.nf
\f[C]
distrobox create --pull --image centos:stream9 --home \[ti]/distrobox/centos9
\f[R]
.fi
.PP
Add additional environment variables to the container
.IP
.nf
\f[C]
distrobox create --image fedora:35 --name test --additional-flags \[dq]--env MY_VAR=value\[dq]
\f[R]
.fi
.PP
Add additional volumes to the container
.IP
.nf
\f[C]
distrobox create --image fedora:35 --name test --volume /opt/my-dir:/usr/local/my-dir:rw --additional-flags \[dq]--pids-limit -1\[dq]
\f[R]
.fi
.PP
Add additional packages to the container
.IP
.nf
\f[C]
distrobox create --image alpine:latest --name test2 --additional-packages \[dq]git tmux vim\[dq]
\f[R]
.fi
.PP
Use init-hooks to perform an action during container startup
.IP
.nf
\f[C]
distrobox create --image alpine:latest --name test --init-hooks \[dq]touch /var/tmp/test1 && touch /var/tmp/test2\[dq]
\f[R]
.fi
.PP
Use pre-init-hooks to perform an action at the beginning of the
container startup (before any package manager starts)
.IP
.nf
\f[C]
distrobox create -i docker.io/almalinux/8-init --init --name test --pre-init-hooks \[dq]dnf config-manager --enable powertools && dnf -y install epel-release\[dq]
\f[R]
.fi
.PP
Use init to create a Systemd container (acts similar to an LXC):
.IP
.nf
\f[C]
distrobox create -i ubuntu:latest --name test --additional-packages \[dq]systemd libpam-systemd\[dq] --init
\f[R]
.fi
.PP
Use init to create a OpenRC container (acts similar to an LXC):
.IP
.nf
\f[C]
distrobox create -i alpine:latest --name test --additional-packages \[dq]openrc\[dq] --init
\f[R]
.fi
.PP
Use host\[cq]s NVidia drivers integration
.IP
.nf
\f[C]
distrobox create --image ubuntu:22.04 --name ubuntu-nvidia --nvidia
\f[R]
.fi
.PP
Do not use host\[cq]s IP inside the container:
.IP
.nf
\f[C]
distrobox create --image ubuntu:latest --name test --unshare-netns
\f[R]
.fi
.PP
Create a more isolated container, where only the $HOME, basic sockets
and host\[cq]s FS (in /run/host) is shared:
.IP
.nf
\f[C]
distrobox create --name unshared-test --unshare-all
\f[R]
.fi
.PP
Create a more isolated container, with it\[cq]s own init system, this
will act very similar to a full LXC container:
.IP
.nf
\f[C]
distrobox create --name unshared-init-test --unshare-all --init --image fedora:latest
\f[R]
.fi
.PP
Use environment variables to specify container name, image and container
manager:
.IP
.nf
\f[C]
DBX_CONTAINER_MANAGER=\[dq]docker\[dq] DBX_NON_INTERACTIVE=1 DBX_CONTAINER_NAME=test-alpine DBX_CONTAINER_IMAGE=alpine distrobox-create
\f[R]
.fi
.SH ENVIRONMENT VARIABLES
.IP
.nf
\f[C]
DBX_CONTAINER_ALWAYS_PULL
DBX_CONTAINER_CUSTOM_HOME
DBX_CONTAINER_HOME_PREFIX
DBX_CONTAINER_IMAGE
DBX_CONTAINER_MANAGER
DBX_CONTAINER_NAME
DBX_CONTAINER_HOSTNAME
DBX_NON_INTERACTIVE
DBX_SUDO_PROGRAM
\f[R]
.fi
.PP
DBX_CONTAINER_HOME_PREFIX defines where containers\[cq] home directories
will be located.
If you define it as \[ti]/dbx then all future containers\[cq] home
directories will be \[ti]/dbx/$container_name
.SH EXTRA
.PP
The \f[V]--additional-flags\f[R] or \f[V]-a\f[R] is useful to modify
defaults in the container creations.
For example:
.IP
.nf
\f[C]
distrobox create -i docker.io/library/archlinux -n dev-arch

podman container inspect dev-arch | jq \[aq].[0].HostConfig.PidsLimit\[aq]
2048

distrobox rm -f dev-arch
distrobox create -i docker.io/library/archlinux -n dev-arch --volume $CBL_TC:/tc --additional-flags \[dq]--pids-limit -1\[dq]

podman container inspect dev-arch | jq \[aq].[0].HostConfig,.PidsLimit\[aq]
0
\f[R]
.fi
.PP
Additional volumes can be specified using the \f[V]--volume\f[R] flag.
This flag follows the same standard as \f[V]docker\f[R] and
\f[V]podman\f[R] to specify the mount point so
\f[V]--volume SOURCE_PATH:DEST_PATH:MODE\f[R].
.IP
.nf
\f[C]
distrobox create --image docker.io/library/archlinux --name dev-arch --volume /usr/share/:/var/test:ro
\f[R]
.fi
.PP
During container creation, it is possible to specify (using the
additional-flags) some environment variables that will persist in the
container and be independent from your environment:
.IP
.nf
\f[C]
distrobox create --image fedora:35 --name test --additional-flags \[dq]--env MY_VAR=value\[dq]
\f[R]
.fi
.PP
The \f[V]--init-hooks\f[R] is useful to add commands to the entrypoint
(init) of the container.
This could be useful to create containers with a set of programs already
installed, add users, groups.
.IP
.nf
\f[C]
distrobox create  --image fedora:35 --name test --init-hooks \[dq]dnf groupinstall -y \[rs]\[dq]C Development Tools and Libraries\[rs]\[dq]\[dq]
\f[R]
.fi
.PP
The \f[V]--init\f[R] is useful to create a container that will use its
own separate init system within.
For example using:
.IP
.nf
\f[C]
distrobox create -i docker.io/almalinux/8-init --init --name test
distrobox create -i docker.io/library/debian --additional-packages \[dq]systemd\[dq] --init --name test-debian
\f[R]
.fi
.PP
Inside the container we will be able to use normal systemd units:
.IP
.nf
\f[C]
\[ti]$ distrobox enter test
user\[at]test:\[ti]$ sudo systemctl enable --now sshd
user\[at]test:\[ti]$ sudo systemctl status sshd
    \[u25CF] sshd.service - OpenSSH server daemon
       Loaded: loaded (/usr/lib/systemd/system/sshd.service; enabled; vendor preset: enabled)
       Active: active (running) since Fri 2022-01-28 22:54:50 CET; 17s ago
         Docs: man:sshd(8)
               man:sshd_config(5)
     Main PID: 291 (sshd)
\f[R]
.fi
.PP
Note that enabling \f[V]--init\f[R] \f[B]will disable host\[cq]s process
integration\f[R].
From within the container you will not be able to see and manage
host\[cq]s processes.
This is needed because \f[V]/sbin/init\f[R] must be pid 1.
.PP
If you want to use a non-pre-create image, you\[cq]ll need to add the
additional package:
.IP
.nf
\f[C]
distrobox create -i alpine:latest --init --additional-packages \[dq]openrc\[dq] -n test
distrobox create -i debian:stable --init --additional-packages \[dq]systemd libpam-systemd\[dq] -n test
distrobox create -i ubuntu:22.04 --init --additional-packages \[dq]systemd libpam-systemd\[dq] -n test
distrobox create -i archlinux:latest --init --additional-packages \[dq]systemd\[dq] -n test
distrobox create -i registry.opensuse.org/opensuse/tumbleweed:latest --init --additional-packages \[dq]systemd\[dq] -n test
distrobox create -i registry.fedoraproject.org/fedora:39 --init --additional-packages \[dq]systemd\[dq] -n test
\f[R]
.fi
.PP
The \f[V]--init\f[R] flag is useful to create system containers, where
the container acts more similar to a full VM than an
application-container.
Inside you\[cq]ll have a separate init, user-session, daemons and so on.
.PP
The \f[V]--home\f[R] flag let\[cq]s you specify a custom HOME for the
container.
Note that this will NOT prevent the mount of the host\[cq]s home
directory, but will ensure that configs and dotfiles will not litter it.
.PP
The \f[V]--root\f[R] flag will let you create a container with real root
privileges.
At first \f[V]enter\f[R] the user will be required to setup a password.
This is done in order to not enable passwordless sudo/su, in a
\f[B]rootful\f[R] container, this is needed because \f[B]in this mode,
root inside the container is also root outside the container!\f[R]
.PP
The
\f[V]--absolutely-disable-root-password-i-am-really-positively-sure\f[R]
will skip user password setup, leaving it blank.
\f[B]This is genuinely dangerous and you really, positively should NOT
enable this\f[R].
.PP
From version 1.4.0 of distrobox, when you create a new container, it
will also generate an entry in the applications list.
.SS NVidia integration
.PP
If your host has an NVidia gpu, with installed proprietary drivers, you
can integrate them with the guests by using the \f[V]--nvidia\f[R] flag:
.PP
\f[V]distrobox create --nvidia --image ubuntu:latest --name ubuntu-nvidia\f[R]
.PP
Be aware that \f[B]this is not compatible with non-glibc systems\f[R]
and \f[B]needs somewhat newer distributions to work\f[R].
.PP
This feature was tested working on:
.IP \[bu] 2
Almalinux
.IP \[bu] 2
Archlinux
.IP \[bu] 2
Centos 7 and newer
.IP \[bu] 2
Clearlinux
.IP \[bu] 2
Debian 10 and newer
.IP \[bu] 2
OpenSUSE Leap
.IP \[bu] 2
OpenSUSE Tumbleweed
.IP \[bu] 2
Rockylinux
.IP \[bu] 2
Ubuntu 18.04 and newer
.IP \[bu] 2
Void Linux (glibc)
.\
.\"
.\" Define V font for inline verbatim, using C font in formats
.\" that render this, and otherwise B font.
.ie "\f[CB]x\f[]"x" \{\
. ftr V B
. ftr VI BI
. ftr VB B
. ftr VBI BI
.\}
.el \{\
. ftr V CR
. ftr VI CI
. ftr VB CB
. ftr VBI CBI
.\}
.TH "DISTROBOX-ENTER" "1" "May 2024" "Distrobox" "User Manual"
.hy
.SH NAME
.IP
.nf
\f[C]
distrobox enter
distrobox-enter
\f[R]
.fi
.SH DESCRIPTION
.PP
distrobox-enter takes care of entering the container with the name
specified.
Default command executed is your SHELL, but you can specify different
shells or entire commands to execute.
If using it inside a script, an application, or a service, you can
specify the \[en]headless mode to disable tty and interactivity.
.SH SYNOPSIS
.PP
\f[B]distrobox enter\f[R]
.IP
.nf
\f[C]
--name/-n:      name for the distrobox                      default: my-distrobox
--/-e:          end arguments execute the rest as command to execute at login   default: default ${USER}\[aq]s shell
--no-tty/-T:        do not instantiate a tty
--no-workdir/-nw:   always start the container from container\[aq]s home directory
--additional-flags/-a:  additional flags to pass to the container manager command
--help/-h:      show this message
--root/-r:      launch podman/docker/lilipod with root privileges. Note that if you need root this is the preferred
            way over \[dq]sudo distrobox\[dq] (note: if using a program other than \[aq]sudo\[aq] for root privileges is necessary,
            specify it through the DBX_SUDO_PROGRAM env variable, or \[aq]distrobox_sudo_program\[aq] config variable)
--dry-run/-d:       only print the container manager command generated
--verbose/-v:       show more verbosity
--version/-V:       show version
\f[R]
.fi
.SH EXAMPLES
.PP
Enter a distrobox named \[lq]example\[rq]
.IP
.nf
\f[C]
distrobox-enter example
\f[R]
.fi
.PP
Enter a distrobox specifying a command
.IP
.nf
\f[C]
distrobox-enter --name fedora-toolbox-35 -- bash -l
distrobox-enter my-alpine-container -- sh -l
\f[R]
.fi
.PP
Use additional podman/docker/lilipod flags while entering a distrobox
.IP
.nf
\f[C]
distrobox-enter --additional-flags \[dq]--preserve-fds\[dq] --name test -- bash -l
\f[R]
.fi
.PP
Specify additional environment variables while entering a distrobox
.IP
.nf
\f[C]
distrobox-enter --additional-flags \[dq]--env MY_VAR=value\[dq] --name test -- bash -l
MY_VAR=value distrobox-enter --additional-flags \[dq]--preserve-fds\[dq] --name test -- bash -l
\f[R]
.fi
.PP
You can also use environment variables to specify container manager and
container name:
.IP
.nf
\f[C]
DBX_CONTAINER_MANAGER=\[dq]docker\[dq] DBX_CONTAINER_NAME=test-alpine distrobox-enter
\f[R]
.fi
.SH ENVIRONMENT VARIABLES
.IP
.nf
\f[C]
DBX_CONTAINER_NAME
DBX_CONTAINER_MANAGER
DBX_SKIP_WORKDIR
DBX_SUDO_PROGRAM
\f[R]
.fi
.SH EXTRA
.PP
This command is used to enter the distrobox itself.
Personally, I just create multiple profiles in my
\f[V]gnome-terminal\f[R] to have multiple distros accessible.
.PP
The \f[V]--additional-flags\f[R] or \f[V]-a\f[R] is useful to modify
default command when executing in the container.
For example:
.IP
.nf
\f[C]
distrobox enter -n dev-arch --additional-flags \[dq]--env my_var=test\[dq] -- printenv &| grep my_var
my_var=test
\f[R]
.fi
.PP
This is possible also using normal env variables:
.IP
.nf
\f[C]
my_var=test distrobox enter -n dev-arch --additional-flags -- printenv &| grep my_var
my_var=test
\f[R]
.fi
.PP
If you\[cq]d like to enter a rootful container having distrobox use a
program other than `sudo' to run podman/docker/lilipod as root, such as
`pkexec' or `doas', you may specify it with the
\f[V]DBX_SUDO_PROGRAM\f[R] environment variable.
For example, to use `doas' to enter a rootful container:
.IP
.nf
\f[C]
DBX_SUDO_PROGRAM=\[dq]doas\[dq] distrobox enter -n container --root
\f[R]
.fi
.PP
Additionally, in one of the config file paths that distrobox supports,
such as \f[V]\[ti]/.distroboxrc\f[R], you can also append the line
\f[V]distrobox_sudo_program=\[dq]doas\[dq]\f[R] (for example) to always
run distrobox commands involving rootful containers using `doas'.
.\
.\"
.\" Define V font for inline verbatim, using C font in formats
.\" that render this, and otherwise B font.
.ie "\f[CB]x\f[]"x" \{\
. ftr V B
. ftr VI BI
. ftr VB B
. ftr VBI BI
.\}
.el \{\
. ftr V CR
. ftr VI CI
. ftr VB CB
. ftr VBI CBI
.\}
.TH "DISTROBOX-EPHEMERAL" "1" "May 2024" "Distrobox" "User Manual"
.hy
.SH NAME
.IP
.nf
\f[C]
distrobox ephemeral
distrobox-ephemeral
\f[R]
.fi
.SH DESCRIPTION
.PP
distrobox-ephemeral creates a temporary distrobox that is automatically
destroyed when the command is terminated.
.SH SYNOPSIS
.PP
\f[B]distrobox ephemeral\f[R]
.IP
.nf
\f[C]
--root/-r:      launch podman/docker/lilipod with root privileges. Note that if you need root this is the preferred
            way over \[dq]sudo distrobox\[dq] (note: if using a program other than \[aq]sudo\[aq] for root privileges is necessary,
            specify it through the DBX_SUDO_PROGRAM env variable, or \[aq]distrobox_sudo_program\[aq] config variable)
--verbose/-v:       show more verbosity
--help/-h:      show this message
--/-e:          end arguments execute the rest as command to execute at login   default: default ${USER}\[aq]s shell
--version/-V:       show version
\f[R]
.fi
.SH EXAMPLES
.IP
.nf
\f[C]
distrobox-ephemeral --image alpine:latest -- cat /etc/os-release
distrobox-ephemeral --root --verbose --image alpine:latest --volume /opt:/opt
\f[R]
.fi
.PP
You can also use flags from \f[B]distrobox-create\f[R] to customize the
ephemeral container to run.
.SH SEE ALSO
.IP
.nf
\f[C]
distrobox-create --help
man distrobox-create
\f[R]
.fi
.SH ENVIRONMENT VARIABLES
.IP
.nf
\f[C]
distrobox-ephemeral calls distrobox-create, SEE ALSO distrobox-create(1) for
a list of supported environment variables to use.
\f[R]
.fi
.\
.\"
.\" Define V font for inline verbatim, using C font in formats
.\" that render this, and otherwise B font.
.ie "\f[CB]x\f[]"x" \{\
. ftr V B
. ftr VI BI
. ftr VB B
. ftr VBI BI
.\}
.el \{\
. ftr V CR
. ftr VI CI
. ftr VB CB
. ftr VBI CBI
.\}
.TH "DISTROBOX-EXPORT" "1" "May 2024" "Distrobox" "User Manual"
.hy
.SH NAME
.IP
.nf
\f[C]
distrobox-export
\f[R]
.fi
.SH DESCRIPTION
.PP
\f[B]Application and binary exporting\f[R]
.PP
distrobox-export takes care of exporting an app or a binary from the
container to the host.
.PP
The exported app will be easily available in your normal launcher and it
will automatically be launched from the container it is exported from.
.SH SYNOPSIS
.PP
\f[B]distrobox-export\f[R]
.IP
.nf
\f[C]
--app/-a:       name of the application to export
--bin/-b:       absolute path of the binary to export
--list-apps:        list applications exported from this container
--list-binaries     list binaries exported from this container, use -ep to specify custom paths to search
--delete/-d:        delete exported application or binary
--export-label/-el: label to add to exported application name.
            Use \[dq]none\[dq] to disable.
            Defaults to (on \[rs]$container_name)
--export-path/-ep:  path where to export the binary
--extra-flags/-ef:  extra flags to add to the command
--enter-flags/-nf:  flags to add to distrobox-enter
--sudo/-S:      specify if the exported item should be run as sudo
--help/-h:      show this message
--verbose/-v:       show more verbosity
--version/-V:       show version
\f[R]
.fi
.PP
You may want to install graphical applications or CLI tools in your
distrobox.
Using \f[V]distrobox-export\f[R] from \f[B]inside\f[R] the container
will let you use them from the host itself.
.SH EXAMPLES
.IP
.nf
\f[C]
distrobox-export --app mpv [--extra-flags \[dq]flags\[dq]] [--delete] [--sudo]
distrobox-export --bin /path/to/bin [--export-path \[ti]/.local/bin] [--extra-flags \[dq]flags\[dq]] [--delete] [--sudo]
\f[R]
.fi
.PP
\f[B]App export example\f[R]
.IP
.nf
\f[C]
distrobox-export --app abiword
\f[R]
.fi
.PP
This tool will simply copy the original \f[V].desktop\f[R] files along
with needed icons, add the prefix
\f[V]/usr/local/bin/distrobox-enter -n distrobox_name -e ...\f[R] to the
commands to run, and save them in your home to be used directly from the
host as a normal app.
.PP
\f[B]Binary export example\f[R]
.IP
.nf
\f[C]
distrobox-export --bin /usr/bin/code --extra-flags \[dq]--foreground\[dq] --export-path $HOME/.local/bin
\f[R]
.fi
.PP
In the case of exporting binaries, you will have to specify
\f[B]where\f[R] to export it (\f[V]--export-path\f[R]) and the tool will
create a little wrapper script that will \f[V]distrobox-enter -e\f[R]
from the host, the desired binary.
This can be handy with the use of \f[V]direnv\f[R] to have different
versions of the same binary based on your \f[V]env\f[R] or project.
.PP
The exported binaries will be exported in the \[lq]\[en]export-path\[rq]
of choice as a wrapper script that acts naturally both on the host and
in the container.
.PP
\f[B]Additional flags\f[R]
.PP
You can specify additional flags to add to the command, for example if
you want to export an electron app, you could add the
\[lq]\[en]foreground\[rq] flag to the command:
.IP
.nf
\f[C]
distrobox-export --app atom --extra-flags \[dq]--foreground\[dq]
distrobox-export --bin /usr/bin/vim --export-path \[ti]/.local/bin --extra-flags \[dq]-p\[dq]
\f[R]
.fi
.PP
This works for binaries and apps.
Extra flags are only used then the exported app or binary is used from
the host, using them inside the container will not include them.
.PP
\f[B]Unexport\f[R]
.PP
The option \[lq]\[en]delete\[rq] will un-export an app or binary
.IP
.nf
\f[C]
distrobox-export --app atom --delete
distrobox-export --bin /usr/bin/vim --export-path \[ti]/.local/bin --delete
\f[R]
.fi
.PP
\f[B]Run as root in the container\f[R]
.PP
The option \[lq]\[en]sudo\[rq] will launch the exported item as root
inside the distrobox.
.PP
\f[B]Notes\f[R]
.PP
Note you can use \[en]app OR \[en]bin but not together.
.PP
[IMAGE: app-export (https://user-images.githubusercontent.com/598882/144294795-c7785620-bf68-4d1b-b251-1e1f0a32a08d.png)]
.PP
NOTE: some electron apps such as vscode and atom need additional flags
to work from inside the container, use the \f[V]--extra-flags\f[R]
option to provide a series of flags, for example:
.PP
\f[V]distrobox-export --app atom --extra-flags \[dq]--foreground\[dq]\f[R]
.\
.\"
.\" Define V font for inline verbatim, using C font in formats
.\" that render this, and otherwise B font.
.ie "\f[CB]x\f[]"x" \{\
. ftr V B
. ftr VI BI
. ftr VB B
. ftr VBI BI
.\}
.el \{\
. ftr V CR
. ftr VI CI
. ftr VB CB
. ftr VBI CBI
.\}
.TH "DISTROBOX-GENERATE-ENTRY" "1" "May 2024" "Distrobox" "User Manual"
.hy
.SH NAME
.IP
.nf
\f[C]
distrobox generate-entry
\f[R]
.fi
.SH DESCRIPTION
.PP
distrobox-generate-entry will create a desktop icon for one of the
available distroboxes.
This will be then deleted when you remove the matching distrobox.
.SH SYNOPSIS
.PP
\f[B]distrobox generate-entry\f[R]
.IP
.nf
\f[C]
--help/-h:      show this message
--all/-a:       perform for all distroboxes
--delete/-d:        delete the entry
--icon/-i:      specify a custom icon [/path/to/icon] (default auto)
--root/-r:      perform on rootful distroboxes
--verbose/-v:       show more verbosity
--version/-V:       show version
\f[R]
.fi
.SH EXAMPLES
.PP
Generate an entry for a container
.IP
.nf
\f[C]
distrobox generate-entry my-container-name
\f[R]
.fi
.PP
Specify a custom icon for the entry
.IP
.nf
\f[C]
distrobox generate-entry my-container-name --icon /path/to/icon.png
\f[R]
.fi
.PP
Generate an entry for all distroboxes
.IP
.nf
\f[C]
distrobox generate-entry --all
\f[R]
.fi
.PP
Delete an entry
.IP
.nf
\f[C]
distrobox generate-entry container-name --delete
\f[R]
.fi
.\
.\"
.\" Define V font for inline verbatim, using C font in formats
.\" that render this, and otherwise B font.
.ie "\f[CB]x\f[]"x" \{\
. ftr V B
. ftr VI BI
. ftr VB B
. ftr VBI BI
.\}
.el \{\
. ftr V CR
. ftr VI CI
. ftr VB CB
. ftr VBI CBI
.\}
.TH "DISTROBOX-HOST-EXEC" "1" "May 2024" "Distrobox" "User Manual"
.hy
.SH NAME
.IP
.nf
\f[C]
distrobox-host-exec
\f[R]
.fi
.SH DESCRIPTION
.PP
distrobox-host-exec lets one execute command on the host, while inside
of a container.
.PP
Under the hood, distrobox-host-exec uses \f[V]host-spawn\f[R] a project
that lets us execute commands back on the host.
If the tool is not found the user will be prompted to install it.
.SH SYNOPSIS
.PP
Just pass to \[lq]distrobox-host-exec\[rq] any command and all its
arguments, if any.
.IP
.nf
\f[C]
--help/-h:      show this message
--verbose/-v:       show more verbosity
--version/-V:       show version
--yes/-Y:       Automatically answer yes to prompt:
                            host-spawn will be installed on the guest system
                            if host-spawn is not detected.
                            This behaviour is default when running in a non-interactive shell.
\f[R]
.fi
.PP
If no command is provided, it will execute \[lq]$SHELL\[rq].
.PP
Alternatively, use symlinks to make \f[V]distrobox-host-exec\f[R]
execute as that command:
.IP
.nf
\f[C]
\[ti]$: ln -s /usr/bin/distrobox-host-exec /usr/local/bin/podman
\[ti]$: ls -l /usr/local/bin/podman
lrwxrwxrwx. 1 root root 51 Jul 11 19:26 /usr/local/bin/podman -> /usr/bin/distrobox-host-exec
\[ti]$: podman version
\&...this is executed on host...
\f[R]
.fi
.SH EXAMPLES
.IP
.nf
\f[C]
distrobox-host-exec ls
distrobox-host-exec bash -l
distrobox-host-exec flatpak run org.mozilla.firefox
distrobox-host-exec podman ps -a
\f[R]
.fi
.\
.\"
.\" Define V font for inline verbatim, using C font in formats
.\" that render this, and otherwise B font.
.ie "\f[CB]x\f[]"x" \{\
. ftr V B
. ftr VI BI
. ftr VB B
. ftr VBI BI
.\}
.el \{\
. ftr V CR
. ftr VI CI
. ftr VB CB
. ftr VBI CBI
.\}
.TH "DISTROBOX-INIT" "1" "May 2024" "Distrobox" "User Manual"
.hy
.SH NAME
.IP
.nf
\f[C]
distrobox-init
\f[R]
.fi
.SH DESCRIPTION
.PP
\f[B]Init the distrobox (not to be launched manually)\f[R]
.PP
distrobox-init is the entrypoint of a created distrobox.
Note that this HAS to run from inside a distrobox, will not work if you
run it from your host.
.PP
\f[B]This is not intended to be used manually, but instead used by
distrobox-create to set up the container\[cq]s entrypoint.\f[R]
.PP
distrobox-init will take care of installing missing dependencies (eg.
sudo), set up the user and groups, mount directories from the host to
ensure the tight integration.
.SH SYNOPSIS
.PP
\f[B]distrobox-init\f[R]
.IP
.nf
\f[C]
--name/-n:      user name
--user/-u:      uid of the user
--group/-g:     gid of the user
--home/-d:      path/to/home of the user
--help/-h:      show this message
--additional-packages:  packages to install in addition
--init/-I:      whether to use or not init
--pre-init-hooks:   commands to execute prior to init
--nvidia:       try to integrate host\[aq]s nVidia drivers in the guest
--upgrade/-U:       run init in upgrade mode
--verbose/-v:       show more verbosity
--version/-V:       show version
--:         end arguments execute the rest as command to execute during init
\f[R]
.fi
.SH EXAMPLES
.IP
.nf
\f[C]
distrobox-init --name test-user --user 1000 --group 1000 --home /home/test-user
distrobox-init --upgrade
\f[R]
.fi
.\
.\"
.\" Define V font for inline verbatim, using C font in formats
.\" that render this, and otherwise B font.
.ie "\f[CB]x\f[]"x" \{\
. ftr V B
. ftr VI BI
. ftr VB B
. ftr VBI BI
.\}
.el \{\
. ftr V CR
. ftr VI CI
. ftr VB CB
. ftr VBI CBI
.\}
.TH "DISTROBOX-LIST" "1" "May 2024" "Distrobox" "User Manual"
.hy
.SH NAME
.IP
.nf
\f[C]
distrobox list
distrobox-list
\f[R]
.fi
.SH DESCRIPTION
.PP
distrobox-list lists available distroboxes.
It detects them and lists them separately from the rest of normal
containers.
.SH SYNOPSIS
.PP
\f[B]distrobox list\f[R]
.IP
.nf
\f[C]
--help/-h:      show this message
--no-color:     disable color formatting
--root/-r:      launch podman/docker/lilipod with root privileges. Note that if you need root this is the preferred
            way over \[dq]sudo distrobox\[dq] (note: if using a program other than \[aq]sudo\[aq] for root privileges is necessary,
            specify it through the DBX_SUDO_PROGRAM env variable, or \[aq]distrobox_sudo_program\[aq] config variable)
--verbose/-v:       show more verbosity
--version/-V:       show version
\f[R]
.fi
.SH EXAMPLES
.IP
.nf
\f[C]
distrobox-list
\f[R]
.fi
.PP
You can also use environment variables to specify container manager
.IP
.nf
\f[C]
DBX_CONTAINER_MANAGER=\[dq]docker\[dq] distrobox-list
\f[R]
.fi
.SH ENVIRONMENT VARIABLES
.IP
.nf
\f[C]
DBX_CONTAINER_MANAGER
DBX_SUDO_PROGRAM
\f[R]
.fi
.PP
[IMAGE: image (https://user-images.githubusercontent.com/598882/147831082-24b5bc2e-b47e-49ac-9b1a-a209478c9705.png)]
.\
.\"
.\" Define V font for inline verbatim, using C font in formats
.\" that render this, and otherwise B font.
.ie "\f[CB]x\f[]"x" \{\
. ftr V B
. ftr VI BI
. ftr VB B
. ftr VBI BI
.\}
.el \{\
. ftr V CR
. ftr VI CI
. ftr VB CB
. ftr VBI CBI
.\}
.TH "DISTROBOX-RM" "1" "May 2024" "Distrobox" "User Manual"
.hy
.SH NAME
.IP
.nf
\f[C]
distrobox rm
distrobox-rm
\f[R]
.fi
.SH DESCRIPTION
.PP
distrobox-rm delete one of the available distroboxes.
.SH SYNOPSIS
.PP
\f[B]distrobox rm\f[R]
.IP
.nf
\f[C]
--all/-a:       delete all distroboxes
--force/-f:     force deletion
--rm-home:      remove the mounted home if it differs from the host user\[aq]s one
--root/-r:      launch podman/docker/lilipod with root privileges. Note that if you need root this is the preferred
            way over \[dq]sudo distrobox\[dq] (note: if using a program other than \[aq]sudo\[aq] for root privileges is necessary,
            specify it through the DBX_SUDO_PROGRAM env variable, or \[aq]distrobox_sudo_program\[aq] config variable)
--help/-h:      show this message
--verbose/-v:       show more verbosity
--version/-V:       show version
\f[R]
.fi
.SH EXAMPLES
.IP
.nf
\f[C]
distrobox-rm container-name [--force] [--all]
\f[R]
.fi
.PP
You can also use environment variables to specify container manager and
name:
.IP
.nf
\f[C]
DBX_CONTAINER_MANAGER=\[dq]docker\[dq] DBX_CONTAINER_NAME=test-alpine distrobox-rm
\f[R]
.fi
.SH ENVIRONMENT VARIABLES
.IP
.nf
\f[C]
DBX_CONTAINER_MANAGER
DBX_CONTAINER_NAME
DBX_NON_INTERACTIVE
DBX_SUDO_PROGRAM
\f[R]
.fi
.\
.\"
.\" Define V font for inline verbatim, using C font in formats
.\" that render this, and otherwise B font.
.ie "\f[CB]x\f[]"x" \{\
. ftr V B
. ftr VI BI
. ftr VB B
. ftr VBI BI
.\}
.el \{\
. ftr V CR
. ftr VI CI
. ftr VB CB
. ftr VBI CBI
.\}
.TH "DISTROBOX-STOP" "1" "May 2024" "Distrobox" "User Manual"
.hy
.SH NAME
.IP
.nf
\f[C]
distrobox stop
distrobox-stop
\f[R]
.fi
.SH DESCRIPTION
.PP
distrobox-stop stop a running distrobox.
.PP
Distroboxes are left running, even after exiting out of them, so that
subsequent enters are really quick.
This is how they can be stopped.
.SH SYNOPSIS
.PP
\f[B]distrobox stop\f[R]
.IP
.nf
\f[C]
--all/-a:       stop all distroboxes
--yes/-Y:       non-interactive, stop without asking
--help/-h:      show this message
--root/-r:      launch podman/docker/lilipod with root privileges. Note that if you need root this is the preferred
            way over \[dq]sudo distrobox\[dq] (note: if using a program other than \[aq]sudo\[aq] for root privileges is necessary,
            specify it through the DBX_SUDO_PROGRAM env variable, or \[aq]distrobox_sudo_program\[aq] config variable)
--verbose/-v:       show more verbosity
--version/-V:       show version
\f[R]
.fi
.SH EXAMPLES
.IP
.nf
\f[C]
distrobox-stop container-name1 container-name2
distrobox-stop container-name
distrobox-stop --all
\f[R]
.fi
.PP
You can also use environment variables to specify container manager and
name:
.IP
.nf
\f[C]
DBX_CONTAINER_MANAGER=\[dq]docker\[dq] DBX_CONTAINER_NAME=test-alpine distrobox-stop
\f[R]
.fi
.SH ENVIRONMENT VARIABLES
.IP
.nf
\f[C]
DBX_CONTAINER_MANAGER
DBX_CONTAINER_NAME
DBX_NON_INTERACTIVE
DBX_SUDO_PROGRAM
\f[R]
.fi
.\
.\"
.\" Define V font for inline verbatim, using C font in formats
.\" that render this, and otherwise B font.
.ie "\f[CB]x\f[]"x" \{\
. ftr V B
. ftr VI BI
. ftr VB B
. ftr VBI BI
.\}
.el \{\
. ftr V CR
. ftr VI CI
. ftr VB CB
. ftr VBI CBI
.\}
.TH "DISTROBOX-UPGRADE" "1" "May 2024" "Distrobox" "User Manual"
.hy
.SH NAME
.IP
.nf
\f[C]
distrobox-upgrade
\f[R]
.fi
.SH DESCRIPTION
.PP
distrobox-upgrade will enter the specified list of containers and will
perform an upgrade using the container\[cq]s package manager.
.SH SYNOPSIS
.PP
\f[B]distrobox upgrade\f[R]
.IP
.nf
\f[C]
--help/-h:      show this message
--all/-a:       perform for all distroboxes
--running:      perform only for running distroboxes
--root/-r:      launch podman/docker/lilipod with root privileges. Note that if you need root this is the preferred
            way over \[dq]sudo distrobox\[dq] (note: if using a program other than \[aq]sudo\[aq] for root privileges is necessary,
            specify it through the DBX_SUDO_PROGRAM env variable, or \[aq]distrobox_sudo_program\[aq] config variable)
--verbose/-v:       show more verbosity
--version/-V:       show version
\f[R]
.fi
.SH EXAMPLES
.PP
Upgrade all distroboxes
.IP
.nf
\f[C]
distrobox-upgrade --all
\f[R]
.fi
.PP
Upgrade all running distroboxes
.IP
.nf
\f[C]
distrobox-upgrade --all --running
\f[R]
.fi
.PP
Upgrade a specific distrobox
.IP
.nf
\f[C]
distrobox-upgrade alpine-linux 
\f[R]
.fi
.PP
Upgrade a list of distroboxes
.IP
.nf
\f[C]
distrobox-upgrade alpine-linux ubuntu22 my-distrobox123
\f[R]
.fi
.PP
\f[B]Automatically update all distro\f[R]
.PP
You can create a systemd service to perform distrobox-upgrade
automatically, this example shows how to run it daily:
.PP
\[ti]/.config/systemd/user/distrobox-upgrade.service
.IP
.nf
\f[C]
[Unit]
Description=distrobox-upgrade Automatic Update

[Service]
Type=simple
ExecStart=distrobox-upgrade --all
StandardOutput=null
\f[R]
.fi
.PP
\[ti]/.config/systemd/user/distrobox-upgrade.timer
.IP
.nf
\f[C]
[Unit]
Description=distrobox-upgrade Automatic Update Trigger

[Timer]
OnBootSec=1h
OnUnitInactiveSec=1d

[Install]
WantedBy=timers.target
\f[R]
.fi
.PP
Then simply do a
\f[V]systemctl --user daemon-reload && systemctl --user enable --now distrobox-upgrade.timer\f[R]