First install

While Exegol supports all major operating systems, we recommend using Linux for optimal performance. Docker Desktop on Windows and macOS has limitations with host network interfaces and USB device access.

Exegol is installed through two main steps:

1. Install the Python wrapper (the "brains")
2. Install at least one Exegol image (the "muscle")

TIP

For the easiest and smoothest experience, we recommend installing Exegol on a Linux system (such as Ubuntu) and using the Zsh shell. Other operating systems and shells are supported, but this setup is by far the most straightforward.

This page details the installation steps for the most common operating systems Ubuntu/Debian, macOS or Windows.

If you're using another operating system in the following list, click on it to be redirected to the proper installation page: Arch, Fedora, Gentoo, NixOS, openSUSE.

If your operating system is not covered here or in the list above, it should work nonetheless, but we probably didn't have the time to document it yet (you're welcome to help if you'd like).

1. Requirements

Before installing Exegol, ensure you have:

• Git: for downloading source code (Linux | macOS | Windows)
• Python 3: to run the wrapper (Linux | macOS | Windows)
• Docker: to run the containers. Docker Engine for Linux, OrbStack is advised for macOS, Docker Desktop for Windows.
• Storage: at least 200GB recommended

Linux is the recommended platform for Exegol. No additional requirements necessary.

Install Git and Python if not already installed:

sudo apt update && sudo apt install -y git python3 pipx

Ensure pipx is in PATH and reload the shell

pipx ensurepath && exec $SHELL

While we always advise to refer to the official documentation, the following one-liner can be used to install Docker quickly.

curl -fsSL "https://get.docker.com/" | sh

WARNING

Docker "Rootless mode" is not supported by Exegol as of yet. Don't follow that part.

2. Wrapper install

Install Exegol in an isolated environment using pipx, a tool that allows you to easily install and run Python applications in isolated environments, keeping them separate from your system Python and other packages.

pipx install exegol

Before using Exegol, you will need to read and accept the End User License Agreement (EULA). This will be prompted on the first run of the wrapper, and until it's confirmed.

To interact with docker, the wrapper needs proper permissions. You must either run Exegol with sudo (preferred), or have your user be a member of the docker group (which dangerously allows your user to basically have root permissions all the time).

The following command shows how to do that with bash, but it can be adapted to any shell. Once the alias is set, you can apply it your current session.

echo "alias exegol='sudo -E $(echo ~/.local/bin/exegol)'" >> ~/.bash_aliases && source ~/.bash_aliases

3. Activation ProEnterprise

If you have a Pro or Enterprise subscription, you can activate your license:

exegol activate

You will need an active license, and a token from dashboard.exegol.com/otp. See the activate documentation section for more information on that action.

4. Image install

Once the wrapper is installed, you can download your first Exegol image:

exegol install

You'll be guided through selecting and installing an image.

5. Run Exegol

Launch your first Exegol container with:

exegol start

⚡ Auto-completion setup

This step is optionnal.

Exegol supports command auto-completion for easier usage. Here's how to set it up for your shell:

First, install argcomplete:

pipx install argcomplete

Then, add the following line to your .bashrc:

eval "$(register-python-argcomplete --no-defaults exegol)"

🌅 Graphical applications support

This step is optionnal. Graphical apps are already usable through the graphical desktop environment already available. This step allows more advanced users to set up X11 socket sharing to open GUI apps from the CLI directly.

Linux supports graphical applications natively.