Install Exegol

Installing Exegol starts with installing the entrypoint to the whole project: the Python wrapper. Once the wrapper is installed, everything else can be managed from it.

Hint

It is strongly advised to install Exegol on a Linux host, especially when planning on using Exegol for internal penetration tests. This is because Docker Desktop on Windows and macOS lacks a few features, mainly due to how these operating systems run Docker containers within an internal VM that doesn’t share the host’s network interfaces and USB accessories.

Once the wrapper is installed, the second step in setting up Exegol on a device is to install at least one Exegol image, either with exegol start (documentation here), or with exegol install (documentation here). Both actions will guide the user in installing an image if needed.

Requirements

The following elements are required before Exegol can be installed, whatever the host’s operating system is:

Additional dependencies may be required depending on the host OS.

No additional dependencies for Linux environments.

Tip

From Linux systems, Docker can be installed quickly and easily with the following command-line:

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

Warning

By default, sudo will be required when running docker, hence needed as well for Exegol. For security reasons, it should stay that way, but it’s possible to change that. In order to run exegol from the user environment without sudo, the user must have the appropriate rights. You can use the following command to grant them to the current user:

# add the sudo group to the user
sudo usermod -aG docker $(id -u -n)

# "reload" the user groups with the newly added docker group
newgrp docker

For more information, official Docker documentation shows how to manage docker as a non root user.

Warning

Docker “Rootless mode” is not supported by Exegol as of yet. Please follow the install procedure mentionned above.

Installation

The installation of Exegol on Linux, macOS and Windows are very similar. It can either be installed from pip (easiest, most user-friendly, but with a few missing features) or from sources (easy as well, fully featured).

1. Installation of exegol

The pre-compiled Exegol’s wrapper can be installed from the PyPI repository. While this is the easiest and most user-friendly technique, it is advised to install from sources, as it allows to switch from release to dev branches easily and it supports the auto-update feature.

Using pipx allows you to install Exegol in an isolated virtual environment dedicated to it.

First, pipx must be installed on your host system:

# install pipx if not already installed, from system package:
sudo apt update && sudo apt install pipx
# OR from pip
python3 -m pip install pipx

Exegol’s wrapper can be installed with pipx from PyPI:

# You can now install Exegol package from PyPI
pipx install exegol

2. Adding Exegol to the PATH

In order to use pipx applications, the pipx environment must be set in your PATH:

pipx ensurepath

Dont forget to open a new terminal to reload your PATH before continuing.

3. Run Exegol with appropriate privileges

Exegol does not support rootless docker. To interact with docker, you must either have your user be a member of the docker group to use exegol as a user, or run Exegol with root privileges using sudo.

To run Exegol as root with sudo, you must use a specific sudo command. For a better user experience, we recommend using an alias:

echo "alias exegol='sudo -E $(which exegol)'" >> ~/.bash_aliases
source ~/.bashrc

4. Installation of the first Exegol image

Once the exegol wrapper is installed, you can download your first docker image with the following command:

exegol install

5. (Optional) Using Exegol auto-completion

Exegol (wrapper) supports auto-completion in many shell environments but there is a configuration to add (on the host) for this feature to work.

Important

The following configurations must be made in your host environment.

Tip

If the command register-python-argcomplete is not found on your host, you have to install it:

# Using the system package manager
sudo apt install python3-argcomplete

# Or using pip (check if pip packages are included in your $PATH)
pip3 install --user argcomplete

# Or using pipx (check if pipx packages are included in your $PATH)
pipx install argcomplete

You can enable Exegol auto-completion for your current user with your .bashrc or you can enable the auto-completion system-wide with bash-completion.

To setup the auto-completion system-wide you first need to install bash-completion on your system (if not already installed).

sudo apt update && sudo apt install bash-completion

At this point you should have a /etc/bash_completion.d/ folder. It’s in there that you can add any auto-completion module that you want.

To generate and install the exegol completion configuration you can execute the following command with register-python-argcomplete:

register-python-argcomplete --no-defaults exegol | sudo tee /etc/bash_completion.d/exegol > /dev/null

Tip

If you have multiple tools using argcomplete you can also use the global completion method (need bash >= 4.2).