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, what a vm lab needs on top, and how to keep the CLI up to date. It is written for anyone working on Linux, including inside a virtual machine, 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.
Prepare the machine for vm labs, and recognise when nested virtualization is missing.
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. The others only become necessary on some labs: Docker as soon as a lab declares services in containers, and all the tooling of vm labs, described below. None is needed to get started.

Two tools come with the CLI and never have to be installed separately: pytest and pytest-testinfra, which run the validation tests. A lab catalogue therefore installs no test tooling at all. ansible-core is also installed in the CLI's isolated environment, but neither uv nor pipx puts its commands in your PATH: the ansible-playbook command, which a vm lab needs, still has to be installed separately.

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.3.5, the latest version published when this lesson was reviewed, or a more recent one. 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.

What a vm lab needs on top

A vm lab does not run in your terminal: it starts real virtual machines on your computer, connects to them over SSH and prepares them with an Ansible playbook. That is the case for 66 of the 86 labs of the Linux catalogue. A page's "Lab" block announces it with its Environment: VM line. Five things must then be in place, and dsoxlab doctor checks them: the hypervisor and /dev/kvm once the provider is chosen, the rest as soon as a catalogue of vm labs is plugged in.

Component	Role	How to get it
`ansible-playbook`	Plays the lab's `setup.yaml` inside the machine	`uv tool install ansible-core`, or `pipx install ansible-core`
A chosen provider	Says where the machines are created	`dsoxlab use --provider kvm`
KVM (libvirt and QEMU), or Incus	The hypervisor that runs the machines	`dsoxlab doctor --fix` installs KVM through `apt` on Debian and Ubuntu
Terraform	Creates and destroys the machines	Install Terraform
An accessible `/dev/kvm`	Hardware virtualization, without which nothing boots	The BIOS of a physical machine, the host hypervisor of a VM

Memory matters too: the three machines of the Linux catalogue share 5120 MB, on top of what your system already uses. The lesson Sizing your machine for the labs gives these figures catalogue by catalogue. The full sequence runs once per catalogue: it installs what is missing, checks, then launches. If doctor still shows a red line, settle it with the gesture it gives before going on:

uv tool install ansible-core       # or: pipx install ansible-core
dsoxlab use --provider kvm         # the provider doctor offers you
dsoxlab doctor                     # the whole required table must be green
dsoxlab instructor bootstrap       # the machines' SSH key, once per clone
dsoxlab start l3-scheduling-cron   # prerequisites, machines, then the lab

dsoxlab start chains the context, the diagnosis, the creation of the machines and the opening of the lab, announcing each step with its command. It is the command to prefer for a first vm lab: when a step fails, it names it and stops there, instead of letting run fail further on, for a less readable reason.

The message about the unavailable vm runtime

On a fresh installation, dsoxlab run on a vm lab answers this, whether the hypervisor is present or not:

✘ Runtime 'vm' is not available on this machine. Install the dependencies
  (`dsoxlab instructor bootstrap`), or pick a lab that runs on another runtime.

The cause is almost always ansible-playbook missing from the PATH, for the reason given above. The message points to instructor bootstrap, but that is not what repairs it: dsoxlab doctor names the failing line, ansible-playbook, with its remedy, uv tool install ansible-core. Once that is settled, run moves on to the next defect and says, for instance, that no machine is running: the sign that you should go through dsoxlab start, which creates the machines before opening the lab.

Inside a virtual machine: nested virtualization

If your Linux itself runs inside a VM, VirtualBox on Windows for instance, the lab's machines would be VMs inside the VM. For that, the host hypervisor must pass hardware virtualization through to your Linux: that is nested virtualization. Without it, /dev/kvm does not exist in your Linux, and dsoxlab doctor says so, naming the hypervisor it detected. Nothing you install inside the guest Linux can produce it: it is set outside, with the machine powered off.

In VirtualBox, select the powered-off machine, then Settings, System, Processor, and tick Enable Nested VT-x/AMD-V. The same option exists on the host command line, with the machine's name as VirtualBox displays it, here debian; the VirtualBox documentation describes both ways:

VBoxManage modifyvm "debian" --nested-hw-virt on

After the restart, ls -l /dev/kvm in your Linux must show the device, and dsoxlab doctor must turn the Hardware virtualization line green. If the box is greyed out, or /dev/kvm is still missing, look at Windows. When the Windows hypervisor, Hyper-V, is active, VirtualBox runs on top of it instead of reaching hardware virtualization directly, and the processor icon in the status bar of the VM window shows it. In that configuration, nesting is not available. That hypervisor is started by WSL2, by Docker Desktop, by Windows Sandbox or by memory integrity: freeing it means turning these features off, and so giving up WSL2 while they are off. It is a trade-off on your computer, not a harmless setting.

When nesting is impossible

A machine that cannot expose /dev/kvm is not a dead end. Three ways remain open, from the simplest to the heaviest:

play the shell labs, which need neither VM nor hypervisor and work wherever the CLI works: the Environment: Shell line of the "Lab" block flags them;
install Linux directly on a machine, as a dual boot or on an old computer, where /dev/kvm depends on the BIOS alone;
choose a cloud provider, when the catalogue declares one: the machines are then created at the hosting company, for a fee, as the lesson Building the infrastructure of vm labs describes.

WSL2 is not among these ways: the dsoxlab documentation does not present it as an environment for vm labs, and this site has not tested it. The appliance does not get around the problem either: it is a VM too, subject to the same nesting rule.

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 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`
`Runtime 'vm' is not available on this machine`	`ansible-playbook` is not in the `PATH`	`uv tool install ansible-core`, then `dsoxlab doctor`
`run` stops on `ProviderUnresolved`	The catalogue offers several providers and none is chosen	`dsoxlab use --provider kvm`
`This lab needs a VM, and none is running`	The lab's machines have not been created	`dsoxlab start <lab-id>`, which creates them before opening the lab
`doctor`: `/dev/kvm is absent` and the system runs inside a VM	Nested virtualization is not enabled on the host	Enable nested VT-x/AMD-V, machine powered off; otherwise, `shell` labs

Key points

Only two prerequisites: Python 3.11 and uv or pipx; git must be present because catalogues are cloned.
pytest and pytest-testinfra come with the CLI: a catalogue installs no test tooling.
A vm lab also needs ansible-playbook, a chosen provider, a hypervisor, Terraform and /dev/kvm; dsoxlab start checks them before creating the machines.
Inside a VM, /dev/kvm requires nested virtualization, enabled on the host with the machine powered off; without it, shell labs remain.
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.