Installing dsoxlab locally with uv or pipx

Installing dsoxlab takes one command, uv tool install dsoxlab or pipx install dsoxlab, and requires no administrator rights. This lesson says what the tool really requires from your machine, how to read the diagnosis of dsoxlab doctor without chasing a component you do not need, and how to keep the CLI up to date. It is written for anyone working on Linux, or on macOS with Python already in place: on Windows, or on a Mac without Python, the right answer is the appliance, covered in the next lesson.

What you will learn

Check the only two prerequisites of the CLI, and know what ships with it.
Install dsoxlab with uv or pipx, then confirm its version.
Interpret the diagnosis of dsoxlab doctor and tell required from informational.
Enable shell completion for bash or zsh.
Update the tool, and tune the daily notice of a new version.

What dsoxlab requires, and what it brings

Two prerequisites, and not one more: Python 3.11 or newer, and a Python tool installer, uv or pipx. Both installers put the CLI in an isolated environment, which avoids any conflict with your system's Python packages. If you have neither, uv installs in one line, without administrator rights, by following its installation documentation.

A third component is required everywhere without being a Python dependency: git, because dsoxlab catalog add clones a repository. It is almost always present already, and dsoxlab doctor names it when it is missing. Two others only become necessary on some labs: Docker as soon as a lab declares services in containers, Terraform as soon as a catalogue carries vm labs. Neither is needed to get started.

Conversely, two tools come with the CLI and never have to be installed separately: pytest and pytest-testinfra, which run the validation tests, and ansible-core, which plays the preparation playbooks of vm labs. A lab catalogue therefore installs no test tooling at all.

Installing and checking the version

The installation puts one command, dsoxlab, and nothing else on your system. Pick the installer you already have:

uv tool install dsoxlab      # or: pipx install dsoxlab
dsoxlab --version

The second command must print dsoxlab 0.2.5, the latest version published when this lesson is written. If the shell answers command not found, the launcher is in place but its directory is not in your PATH: each installer has a command to add it, uv tool update-shell for uv and pipx ensurepath for pipx, to be followed by a new terminal.

Reading the doctor diagnosis

dsoxlab doctor only reports what the current catalogue needs, and sorts its findings into two tables. The first, "required for this repo", lists what blocks you here; the second, "informational", lists the components this catalogue does not use. A missing hypervisor therefore never shows up in red on a catalogue made of shell labs.

dsoxlab doctor

On the demonstration catalogue, the required table carries Python, pytest, the shell runtime, git and the count of labs detected, all green if the installation succeeded. Every red line carries opposite it the gesture that repairs it: a command when one exists, an installation page when only a human can decide.

Three options complete the command, and each answers a precise use:

Option	What it does
`--fix`	Plays the risk-free remedies, such as installing libvirt and QEMU through `apt`, the only package manager the remedies know. A remedy that requires logging back in or rebooting stays red until then, and says so.
`--strict`	Turns the diagnosis into an exit code, `9` when a required check fails, `10` when it could not be measured. Without it, `doctor` always exits `0`: for a human, a diagnosis is not a failure.
`--json`	Renders the same diagnosis as a machine document, with a stable token per check. Incompatible with `--fix`.

A check has three outcomes, never two: ok, failed, and unknown when the probe itself did not complete. That third value does not count in the displayed verdict, because you do not paint in red what you do not know, but --strict gives it its own exit code: a script can conclude nothing from a measurement that did not take place.

Playing the demonstration lab

Nothing beats a lab to confirm that an installation works. The demo command installs a catalogue with a single lab under ~/.local/share/dsoxlab/demo and says what to do next. That lab runs in the shell runtime: no virtual machine, no container, so it works wherever the CLI works.

dsoxlab demo
cd ~/.local/share/dsoxlab/demo
dsoxlab course premiers-pas     # the lesson
dsoxlab run premiers-pas        # drops you into the working directory
dsoxlab challenge premiers-pas  # the mission
dsoxlab check premiers-pas      # the tests, and the score

Count five minutes. The complete walkthrough, with the score panel and the working directory trap, is described on the overview page of the training path.

Enabling shell completion

Completion saves you from remembering lab identifiers, which are long. It installs once, for bash or zsh, and takes effect the next time the shell is reloaded:

dsoxlab completion install      # writes the completion for the current shell
dsoxlab completion show         # prints the script without writing anything

Under zsh, the command writes ~/.zfunc/_dsoxlab and adds a line to ~/.zshrc; under bash, ~/.bash_completion.d/dsoxlab and a line to ~/.bashrc. The older dsoxlab install command still does the same thing but is deprecated: do not make a habit of it.

Choosing the language

Every message of the CLI exists in English and French, and the language is set at two scopes. The environment variable lasts for one call, the catalogue context lasts durably:

DSOXLAB_LANG=en dsoxlab list-labs     # for one call
dsoxlab use linux --lang en           # durably, for this catalogue

The priority, from strongest to weakest: DSOXLAB_LANG, then the catalogue's context file, then the system LANG, then en. A machine in en_US.UTF-8 therefore gets English without any setting, and a machine in fr_FR.UTF-8 gets French unless one of the two commands above says otherwise.

Keeping the tool up to date

dsoxlab looks once a day for a newer version on PyPI, and says so at the end of a command, on standard error so as never to pollute a --json output. Offline, it stays silent. Updating goes through the installer that put the tool in place:

uv tool upgrade dsoxlab            # or: pipx upgrade dsoxlab
DSOXLAB_NO_UPDATE_CHECK=1 dsoxlab list-labs   # silence the notice, for one call

Updating the tool before a catalogue is not a preference: a lab file written for a contract newer than the tool is discarded, whereas an older file read by a newer tool keeps working. When a catalogue announces a version bump, the tool gets updated first.

Troubleshooting

The three cases below cover most of what blocks between the installation and the first lab. Each is recognised by its symptom and fixed without reinstalling.

Symptom	Cause	Solution
`dsoxlab: command not found` right after installing	The launcher directory of `uv` or `pipx` is not in the `PATH`	`uv tool update-shell` or `pipx ensurepath`, then open a new terminal
`dsoxlab catalog add` fails and names `git`	`git` is not installed: the CLI clones catalogues	Install `git` with the system package manager, then run `dsoxlab doctor` again
`dsoxlab --version` prints a version older than the one announced	A launcher from a previous installation comes before the new one	Remove `~/.local/bin/dsoxlab` if it comes from an old `dsoxlab install`, then `uv tool upgrade dsoxlab`

Key points

Only two prerequisites: Python 3.11 and uv or pipx; git must be present because catalogues are cloned.
pytest, pytest-testinfra and ansible-core come with the CLI: a catalogue installs no test tooling.
dsoxlab doctor separates the required from the informational; --fix repairs what can be repaired safely, --strict serves scripts.
A check has three outcomes, ok, failed and unknown: a probe that could not measure never concludes green.
dsoxlab completion install replaces the older dsoxlab install, which is deprecated.
Update the tool before the catalogue, never the other way round.

Next steps

Sizing your machine for the labs: what each catalogue declares in memory, CPU and disk before you install a hypervisor.
The main dsoxlab commands: from catalog add to check, the order in which the commands chain.
Files, environment variables and exit codes: where the CLI writes on disk, and what gesture each exit code calls for.