Installer dsoxlab en local avec uv ou pipx

15 min

Par Stéphane Robert mis à jour le 14 octobre 2026

Améliorer cette page

Que voulez-vous signaler ?

L’issue s’ouvre déjà remplie avec le titre et l’adresse de cette page.

Installer dsoxlab tient en une commande, uv tool install dsoxlab ou pipx install dsoxlab, et ne demande aucun droit d'administration. Cette leçon dit ce que l'outil exige réellement de votre poste, comment lire le diagnostic de dsoxlab doctor sans courir après un composant inutile, ce qu'un lab vm demande en plus, et comment garder la CLI à jour. Elle s'adresse à qui travaille sous Linux, y compris dans une machine virtuelle, ou sous macOS avec Python déjà en place : sous Windows, ou sur un Mac sans Python, la bonne réponse est l'appliance, traitée dans la leçon suivante.

Ce que vous allez apprendre

Vérifier les deux seuls prérequis de la CLI, et savoir ce qui vient avec elle.
Installer dsoxlab avec uv ou pipx, puis confirmer sa version.
Interpréter le diagnostic de dsoxlab doctor et distinguer requis et informatif.
Préparer le poste pour les labs vm, et reconnaître quand la virtualisation imbriquée manque.
Activer l'auto-complétion pour bash ou zsh.
Mettre à jour l'outil, et régler l'avis quotidien de nouvelle version.

Ce que dsoxlab exige, et ce qu'il apporte

Deux prérequis, et pas un de plus : Python 3.11 ou plus récent, et un installeur d'outils Python, uv ou pipx. Ces deux installeurs posent la CLI dans un environnement isolé, ce qui évite tout conflit avec les paquets Python de votre système. Si vous n'avez ni l'un ni l'autre, uv s'installe en une ligne, sans droit d'administration, en suivant sa documentation d'installation.

Un troisième composant est requis partout sans être une dépendance Python : git, parce que dsoxlab catalog add clone un dépôt. Il est presque toujours déjà présent, et dsoxlab doctor le nomme s'il manque. Les autres ne deviennent nécessaires que sur certains labs : Docker dès qu'un lab déclare des services en conteneur, et tout l'outillage des labs vm, décrit plus bas. Aucun n'est utile pour commencer.

Deux outils viennent avec la CLI et n'ont jamais à être installés à part : pytest et pytest-testinfra, qui exécutent les tests de validation. Un catalogue de labs n'installe donc aucun outillage de test. ansible-core est lui aussi installé dans l'environnement isolé de la CLI, mais ni uv ni pipx ne posent ses commandes dans votre PATH : la commande ansible-playbook, dont un lab vm a besoin, reste donc à installer à part.

Installer et vérifier la version

L'installation pose une commande, dsoxlab, et rien d'autre dans votre système. Choisissez l'installeur que vous avez déjà :

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

La seconde commande doit afficher dsoxlab 0.3.5, la dernière version publiée au moment où cette leçon est relue, ou une version plus récente. Si le shell répond command not found, le lanceur est bien posé mais son répertoire n'est pas dans votre PATH : chaque installeur a une commande pour l'y ajouter, uv tool update-shell pour uv et pipx ensurepath pour pipx, à faire suivre d'un nouveau terminal.

Lire le diagnostic de doctor

dsoxlab doctor ne rapporte que ce dont le catalogue courant a besoin, et range ses constats en deux tableaux. Le premier, « requis pour ce dépôt », liste ce qui vous bloque ici ; le second, « informatif », liste les composants dont ce catalogue ne se sert pas. Un hyperviseur absent n'apparaît donc jamais en rouge sur un catalogue fait de labs shell.

dsoxlab doctor

Sur le catalogue de démonstration, le tableau requis porte Python, pytest, le runtime shell, git et le compte de labs détectés, tous verts si l'installation a réussi. Chaque ligne rouge porte en face le geste qui la répare : une commande quand elle existe, une page d'installation quand seul un humain peut décider.

Trois options complètent la commande, et chacune répond à un usage précis :

Option	Ce qu'elle fait
`--fix`	Joue les remèdes sans risque, comme l'installation de libvirt et QEMU par `apt`, le seul gestionnaire de paquets que les remèdes connaissent. Une remédiation qui exige une reconnexion ou un redémarrage reste rouge jusque-là, et le dit.
`--strict`	Traduit le diagnostic en code de sortie, `9` si un contrôle requis échoue, `10` s'il n'a pas pu être mesuré. Sans elle, `doctor` sort toujours en `0` : pour un humain, un diagnostic n'est pas un échec.
`--json`	Rend le même diagnostic sous forme de document machine, avec un jeton stable par contrôle. Incompatible avec `--fix`.

Un contrôle a trois issues, jamais deux : ok, failed, et unknown quand la sonde elle-même n'a pas abouti. Cette troisième valeur ne compte pas dans le verdict affiché, parce qu'on ne peint pas en rouge ce qu'on ignore, mais --strict lui donne son propre code de sortie : un script ne peut rien conclure d'une mesure qui n'a pas eu lieu.

Jouer le lab de démonstration

Rien ne vaut un lab pour confirmer qu'une installation fonctionne. La commande demo installe un catalogue d'un seul lab sous ~/.local/share/dsoxlab/demo et dit quoi faire ensuite. Ce lab tourne en runtime shell : ni machine virtuelle, ni conteneur, donc il fonctionne partout où la CLI fonctionne.

dsoxlab demo
cd ~/.local/share/dsoxlab/demo
dsoxlab course premiers-pas     # la leçon
dsoxlab run premiers-pas        # vous dépose dans le répertoire de travail
dsoxlab challenge premiers-pas  # la mission
dsoxlab check premiers-pas      # les tests, et la note

Comptez cinq minutes. Le déroulé complet, avec le panneau de score et le piège du répertoire de travail, est décrit sur la page d'accueil de la formation.

Ce qu'un lab vm demande en plus

Un lab vm ne se joue pas dans votre terminal : il démarre de vraies machines virtuelles sur votre poste, s'y connecte en SSH et les prépare avec un playbook Ansible. C'est le cas de 66 des 86 labs du catalogue Linux. Le bloc « Lab » d'une page l'annonce par sa ligne Environnement : VM. Cinq choses doivent alors être en place, et dsoxlab doctor les contrôle : l'hyperviseur et /dev/kvm dès que le provider est choisi, le reste dès qu'un catalogue de labs vm est branché.

Composant	Rôle	Comment l'obtenir
`ansible-playbook`	Joue le `setup.yaml` du lab dans la machine	`uv tool install ansible-core`, ou `pipx install ansible-core`
Un provider choisi	Dit où créer les machines	`dsoxlab use --provider kvm`
KVM (libvirt et QEMU), ou Incus	L'hyperviseur qui fait tourner les machines	`dsoxlab doctor --fix` installe KVM par `apt` sur Debian et Ubuntu
Terraform	Crée et détruit les machines	Installer Terraform
`/dev/kvm` accessible	La virtualisation matérielle, sans laquelle rien ne démarre	Le BIOS d'une machine physique, l'hyperviseur hôte d'une VM

La mémoire compte aussi : les trois machines du catalogue Linux se partagent 5120 Mo, en plus de ce que votre système utilise déjà. La leçon Dimensionner sa machine pour les labs donne ces chiffres catalogue par catalogue. La séquence complète se fait une fois par catalogue : elle installe ce qui manque, contrôle, puis lance. Si doctor affiche encore une ligne rouge, réglez-la avec le geste qu'il indique avant de continuer :

uv tool install ansible-core       # ou : pipx install ansible-core
dsoxlab use --provider kvm         # le provider que doctor vous propose
dsoxlab doctor                     # tout le tableau requis doit être vert
dsoxlab instructor bootstrap       # la clé SSH des machines, une fois par clone
dsoxlab start l3-scheduling-cron   # prérequis, machines, puis le lab

dsoxlab start enchaîne le contexte, le diagnostic, la création des machines et l'ouverture du lab, en annonçant chaque étape avec sa commande. C'est la commande à préférer pour un premier lab vm : quand une étape échoue, il la nomme et s'arrête là, au lieu de laisser run échouer plus loin sur une cause moins lisible.

Le message sur le runtime vm indisponible

Sur une installation neuve, dsoxlab run sur un lab vm répond ceci, que l'hyperviseur soit présent ou non :

✘ Le runtime « vm » n'est pas disponible sur cette machine. Installe les
  dépendances (`dsoxlab instructor bootstrap`), ou utilise un lab compatible
  avec un autre runtime.

La cause est presque toujours ansible-playbook absent du PATH, pour la raison donnée plus haut. Le message renvoie à instructor bootstrap, mais ce n'est pas lui qui répare : dsoxlab doctor nomme la ligne en défaut, ansible-playbook, avec sa remédiation, uv tool install ansible-core. Une fois ce point réglé, run passe au défaut suivant et dit, par exemple, qu'aucune machine ne tourne : c'est le signe qu'il faut passer par dsoxlab start, qui crée les machines avant d'ouvrir le lab.

Dans une machine virtuelle : la virtualisation imbriquée

Si votre Linux tourne lui-même dans une VM, VirtualBox sous Windows par exemple, les machines du lab seraient des VM dans la VM. Il faut pour cela que l'hyperviseur hôte transmette la virtualisation matérielle à votre Linux : c'est la virtualisation imbriquée. Sans elle, /dev/kvm n'existe pas dans votre Linux, et dsoxlab doctor le dit en nommant l'hyperviseur détecté. Rien de ce que vous installez dans le Linux invité ne peut la produire : elle se règle à l'extérieur, la machine éteinte.

Dans VirtualBox, sélectionnez la machine éteinte, puis Configuration, Système, Processeur, et cochez Activer VT-x/AMD-V imbriqué. La même option existe en ligne de commande sur l'hôte, avec le nom de la machine tel que VirtualBox l'affiche, ici debian ; la documentation de VirtualBox décrit les deux voies :

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

Au redémarrage, ls -l /dev/kvm dans votre Linux doit montrer le périphérique, et dsoxlab doctor passer la ligne Virtualisation matérielle au vert. Si la case est grisée, ou si /dev/kvm manque toujours, regardez du côté de Windows. Quand l'hyperviseur de Windows, Hyper-V, est actif, VirtualBox s'exécute par-dessus lui au lieu d'accéder directement à la virtualisation matérielle, et l'icône du processeur dans la barre d'état de la fenêtre de la VM le signale. Dans cette configuration, l'imbrication n'est pas disponible. Cet hyperviseur est démarré par WSL2, par Docker Desktop, par le bac à sable Windows ou par l'intégrité de la mémoire : le libérer impose de désactiver ces fonctions, donc de renoncer à WSL2 tant qu'elles sont coupées. C'est un arbitrage sur votre poste, pas un réglage anodin.

Quand l'imbrication est impossible

Une machine qui ne peut pas exposer /dev/kvm n'est pas une impasse. Trois voies restent ouvertes, de la plus simple à la plus lourde :

jouer les labs shell, qui ne demandent ni VM ni hyperviseur et fonctionnent partout où la CLI fonctionne : la ligne Environnement : Shell du bloc « Lab » les signale ;
installer Linux directement sur une machine, en double démarrage ou sur un ancien ordinateur, où /dev/kvm dépend du seul BIOS ;
choisir un provider cloud, quand le catalogue en déclare un : les machines sont alors créées chez l'hébergeur, contre facturation, comme le décrit la leçon Monter l'infrastructure des labs vm.

WSL2 ne figure pas parmi ces voies : la documentation de dsoxlab ne le présente pas comme un environnement pour les labs vm, et ce site ne l'a pas éprouvé. L'appliance ne contourne pas non plus le problème : c'est elle aussi une VM, soumise à la même règle d'imbrication.

Activer l'auto-complétion

La complétion évite de retenir les identifiants de labs, qui sont longs. Elle s'installe une fois, pour bash ou zsh, et prend effet au prochain rechargement du shell :

dsoxlab completion install      # écrit la complétion pour le shell courant
dsoxlab completion show         # imprime le script sans rien écrire

Sous zsh, la commande écrit ~/.zfunc/_dsoxlab et ajoute une ligne à ~/.zshrc ; sous bash, ~/.bash_completion.d/dsoxlab et une ligne à ~/.bashrc. L'ancienne commande dsoxlab install fait encore la même chose mais est dépréciée : n'en prenez pas l'habitude.

Choisir la langue

Chaque message de la CLI existe en anglais et en français, et la langue se règle à deux portées. La variable d'environnement vaut le temps d'un appel, le contexte de catalogue vaut durablement :

DSOXLAB_LANG=fr dsoxlab list-labs     # le temps d'un appel
dsoxlab use linux --lang fr           # durablement, pour ce catalogue

La priorité, de la plus forte à la plus faible : DSOXLAB_LANG, puis le fichier de contexte du catalogue, puis le LANG du système, puis en. Un poste en fr_FR.UTF-8 obtient donc le français sans rien régler.

Tenir l'outil à jour

dsoxlab regarde une fois par jour si une version plus récente existe sur PyPI, et le dit en fin de commande, sur la sortie d'erreur pour ne jamais polluer une sortie --json. Hors ligne, il se tait. La mise à jour passe par l'installeur qui a posé l'outil :

uv tool upgrade dsoxlab            # ou : pipx upgrade dsoxlab
DSOXLAB_NO_UPDATE_CHECK=1 dsoxlab list-labs   # couper l'avis, le temps d'un appel

Mettre l'outil à jour avant un catalogue n'est pas une préférence : un fichier de lab écrit pour un contrat plus récent que l'outil est écarté, alors qu'un fichier ancien lu par un outil récent fonctionne toujours. Quand un catalogue annonce une montée de version, l'outil se met à jour en premier.

Dépannage

Les cas ci-dessous couvrent l'essentiel de ce qui bloque entre l'installation et le premier lab. Chacun se reconnaît à son symptôme et se règle sans réinstaller.

Symptôme	Cause	Solution
`dsoxlab: command not found` juste après l'installation	Le répertoire des lanceurs de `uv` ou `pipx` n'est pas dans le `PATH`	`uv tool update-shell` ou `pipx ensurepath`, puis ouvrir un nouveau terminal
`dsoxlab catalog add` échoue en nommant `git`	`git` n'est pas installé : la CLI clone les catalogues	Installer `git` avec le gestionnaire de paquets du système, puis relancer `dsoxlab doctor`
`dsoxlab --version` affiche une version plus ancienne que celle annoncée	Un lanceur d'une installation précédente passe avant le nouveau	Retirer `~/.local/bin/dsoxlab` s'il vient d'un ancien `dsoxlab install`, puis `uv tool upgrade dsoxlab`
`Le runtime « vm » n'est pas disponible sur cette machine`	`ansible-playbook` n'est pas dans le `PATH`	`uv tool install ansible-core`, puis `dsoxlab doctor`
`run` s'arrête sur `ProviderUnresolved`	Le catalogue propose plusieurs providers et aucun n'est choisi	`dsoxlab use --provider kvm`
`Ce lab a besoin d'une VM, et aucune ne tourne`	Les machines du lab n'ont pas été créées	`dsoxlab start <identifiant-du-lab>`, qui les crée avant d'ouvrir le lab
`doctor` : `/dev/kvm est absent` et le système tourne dans une VM	La virtualisation imbriquée n'est pas activée sur l'hôte	Activer VT-x/AMD-V imbriqué, machine éteinte ; sinon, labs `shell`

À retenir

Deux prérequis seulement : Python 3.11 et uv ou pipx ; git doit être présent parce que les catalogues se clonent.
pytest et pytest-testinfra viennent avec la CLI : un catalogue n'installe aucun outillage de test.
Un lab vm demande en plus ansible-playbook, un provider choisi, un hyperviseur, Terraform et /dev/kvm ; dsoxlab start les vérifie avant de créer les machines.
Dans une VM, /dev/kvm exige la virtualisation imbriquée, activée sur l'hôte, machine éteinte ; sans elle, restent les labs shell.
dsoxlab doctor sépare le requis de l'informatif ; --fix répare ce qui l'est sans risque, --strict sert aux scripts.
Un contrôle a trois issues, ok, failed et unknown : une sonde qui n'a pas pu mesurer ne conclut jamais au vert.
dsoxlab completion install remplace l'ancien dsoxlab install, déprécié.
On met l'outil à jour avant le catalogue, jamais l'inverse.