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:
- Install the Python wrapper (the "brains")
- Install at least one Exegol image (the "muscle")
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
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.