asdf : un gestionnaire de versions universel pour DevOps

asdf remplace nvm, pyenv, rbenv et tous les gestionnaires de versions spécifiques par un seul outil. Avec une commande unique (asdf install), vous installez Node.js, Python, Go, Terraform, kubectl et plus de 700 outils. Le fichier .tool-versions à la racine de chaque projet garantit que toute l'équipe utilise exactement les mêmes versions. Fini les "ça marche sur ma machine".

En 30 secondes

# Installer Node.js 22 et Python 3.12 pour un projet
asdf plugin add nodejs && asdf plugin add python
asdf install nodejs 22.13.1 && asdf install python 3.12.8
asdf set nodejs 22.13.1 && asdf set python 3.12.8
# Le fichier .tool-versions est créé automatiquement

Ce que vous allez apprendre

• Comprendre le fonctionnement d'asdf (plugins, shims, résolution de versions)
• Installer asdf sur Linux et macOS
• Gérer vos outils : installer, définir des versions globales et locales
• Synchroniser une équipe avec le fichier .tool-versions
• Migrer depuis nvm, pyenv ou rbenv
• Optimiser votre workflow avec les bonnes pratiques

Alternative moderne : mise

Si vous débutez, considérez mise (ex-rtx), un gestionnaire de versions plus récent, plus rapide et compatible avec asdf. asdf reste pertinent si vous avez des projets existants ou besoin de plugins spécifiques.

Fonctionnement de asdf

asdf ne sait rien faire seul : chaque outil géré passe par un plugin, un petit dépôt de scripts shell qui sait lister, télécharger et compiler les versions de cet outil. Une fois la version installée, asdf place dans le PATH un shim, un script intermédiaire qui intercepte l'appel à node ou terraform et le redirige vers le binaire de la version active. Cette indirection explique deux choses : pourquoi which node renvoie toujours un chemin dans ~/.asdf/shims/, et pourquoi il faut parfois regénérer les shims après une installation.

asdf repose sur trois concepts clés :

Concept	Description	Exemple
Plugin	Extension pour gérer un outil spécifique	asdf-nodejs, asdf-python
Shim	Wrapper qui redirige vers la bonne version	~/.asdf/shims/node
Version	Instance installée d'un outil	nodejs 22.13.1

Glissez pour voir

Comment asdf choisit la version ? (ordre de priorité)

1. Variable d'environnement ASDF_<TOOL>_VERSION
2. Fichier .tool-versions dans le répertoire courant
3. Fichier .tool-versions dans les répertoires parents (remontée)
4. Fichier ~/.tool-versions (version globale)

Où sont stockés les outils ?

~/.asdf/
├── installs/        # Versions installées
│   ├── nodejs/
│   │   └── 22.13.1/
│   └── python/
│       └── 3.12.8/
├── plugins/         # Plugins installés
├── shims/           # Wrappers (à ajouter au PATH)
└── .tool-versions   # Versions globales

Installation de asdf

L'installation se déroule en deux temps : poser le binaire asdf, puis modifier la configuration du shell pour que le répertoire des shims arrive en tête du PATH. La seconde étape n'est pas facultative : sans elle, asdf s'installe correctement mais aucune de vos commandes ne passe par lui. Sur Linux, asdf se récupère sous forme de binaire précompilé, il n'y a ni dépôt Git à cloner ni script à sourcer.

Linux

1. Télécharger le binaire

   wget https://github.com/asdf-vm/asdf/releases/download/v0.18.0/asdf-v0.18.0-linux-amd64.tar.gz
   tar -xvzf asdf-v0.18.0-linux-amd64.tar.gz -C ${HOME}/.local/bin
   chmod +x ${HOME}/.local/bin/asdf

2. Configurer le shell (Bash)

   echo 'export PATH="${ASDF_DATA_DIR:-$HOME/.asdf}/shims:$PATH"' >> ~/.bashrc
   echo '. <(asdf completion bash)' >> ~/.bashrc
   source ~/.bashrc

3. Configurer le shell (Zsh)

   echo 'export PATH="${ASDF_DATA_DIR:-$HOME/.asdf}/shims:$PATH"' >> ~/.zshrc
   mkdir -p "${ASDF_DATA_DIR:-$HOME/.asdf}/completions"
   asdf completion zsh > "${ASDF_DATA_DIR:-$HOME/.asdf}/completions/_asdf"

   Ajoutez cette ligne avant autoload -Uz compinit && compinit :

   fpath=(${ASDF_DATA_DIR:-$HOME/.asdf}/completions $fpath)

4. Vérifier l'installation

   asdf --version

   Résultat attendu : asdf version v0.18.0

macOS

1. Installer avec Homebrew

   brew install asdf

2. Configurer le shell (Zsh - défaut macOS)

   echo -e "\n. $(brew --prefix asdf)/libexec/asdf.sh" >> ~/.zshrc
   source ~/.zshrc

3. Vérifier l'installation

   asdf --version

Commandes essentielles

Toutes les commandes suivent la même forme : un verbe (plugin, install, list, set, current) suivi du nom de l'outil. Retenez surtout la distinction entre install, qui télécharge une version sur le disque, et set, qui désigne celle qui doit être active. Installer sans définir ne change rien à ce que votre shell exécute.

Gérer les plugins

Un plugin ne s'ajoute qu'une fois par machine ; il est ensuite partagé par tous vos projets.

# Lister les plugins disponibles (700+)
asdf plugin list all | head -20

# Ajouter un plugin
asdf plugin add nodejs
asdf plugin add python
asdf plugin add golang
asdf plugin add terraform

# Lister les plugins installés
asdf plugin list

# Mettre à jour un plugin
asdf plugin update nodejs

# Mettre à jour tous les plugins
asdf plugin update --all

# Supprimer un plugin
asdf plugin remove nodejs

Installer des versions

Lancé sans argument, asdf install lit le .tool-versions du répertoire courant et installe d'un coup tout ce que le projet réclame.

# Lister les versions disponibles
asdf list all nodejs | tail -10

# Installer une version spécifique
asdf install nodejs 22.13.1
asdf install python 3.12.8

# Installer la dernière version stable
asdf install nodejs latest

# Lister les versions installées
asdf list nodejs

Définir les versions actives

asdf set écrit dans le .tool-versions du répertoire courant, tandis que --home écrit dans ~/.tool-versions ; ces deux fichiers sont du texte brut, lisible et modifiable à la main.

# Version globale (pour tout le système)
asdf set --home nodejs 22.13.1

# Version locale (pour le projet courant)
cd mon-projet
asdf set nodejs 20.18.0

# Vérifier la version active
asdf current nodejs

# Vérifier toutes les versions actives
asdf current

Désinstaller

Désinstaller une version libère la place occupée sous ~/.asdf/installs/ ; retirer le plugin supprime au passage toutes les versions de l'outil, sans confirmation ni retour possible.

# Désinstaller une version
asdf uninstall nodejs 20.18.0

# Supprimer un plugin (et toutes ses versions)
asdf plugin remove nodejs

Synchroniser une équipe avec .tool-versions

Le fichier .tool-versions est la clé pour garantir des environnements identiques. Placez-le à la racine de votre projet et committez-le.

.tool-versions

nodejs 22.13.1
python 3.12.8
terraform 1.9.8
kubectl 1.31.4

Workflow équipe :

1. Cloner le projet

   git clone https://github.com/mon-org/mon-projet.git
   cd mon-projet

2. Installer les plugins nécessaires

   # Script d'installation automatique
   for plugin in $(cut -d' ' -f1 .tool-versions); do
     asdf plugin add "$plugin" 2>/dev/null || true
   done

3. Installer toutes les versions

   asdf install

   Cette commande lit .tool-versions et installe toutes les versions manquantes.

4. Vérifier

   asdf current

Compatibilité avec d'autres fichiers

asdf reconnaît aussi .node-version, .nvmrc, .ruby-version et .python-version. Pratique pour migrer progressivement.

Astuces et bonnes pratiques

Ces recettes ne font pas partie d'asdf : ce sont des scripts et des alias à poser dans votre configuration de shell. Elles répondent aux besoins qui apparaissent une fois asdf adopté sur plusieurs projets : maintenir les outils à jour, comprendre pourquoi telle version est active, et rejouer sa configuration sur une machine neuve.

Mettre à jour tous vos outils en une commande

Cette boucle installe la dernière version de chaque plugin puis la déclare comme version globale ; elle ne touche pas aux .tool-versions de vos projets.

for tool in $(asdf plugin list); do
  latest=$(asdf latest "$tool" 2>/dev/null)
  if [[ -n "$latest" ]]; then
    asdf install "$tool" "$latest" \
      && asdf set --home "$tool" "$latest" \
      && echo "✅ $tool → $latest"
  fi
done

Vérifier les mises à jour disponibles

asdf latest --all compare la dernière version publiée de chaque plugin à ce qui est présent sur la machine, sans rien installer.

asdf latest --all

Résultat :

golang   1.23.5   installed
helm     3.17.1   missing
k9s      0.32.7   missing
nodejs   23.7.0   missing
python   3.13.2   missing

Créer un alias pour les commandes fréquentes

Ajoutez à votre .bashrc ou .zshrc :

# Installer la dernière version d'un outil
alias asdf-latest='asdf install $1 latest && asdf set --home $1 latest'

# Nettoyer les anciennes versions
asdf-cleanup() {
  for plugin in $(asdf plugin list); do
    versions=$(asdf list "$plugin" 2>/dev/null | wc -l)
    if [[ $versions -gt 1 ]]; then
      echo "🧹 $plugin a $versions versions installées"
    fi
  done
}

Sauvegarder votre configuration globale

Le fichier ~/.tool-versions est du texte brut : le copier dans vos dotfiles suffit à reconstituer l'outillage complet ailleurs.

# Exporter vos versions globales
cp ~/.tool-versions ~/dotfiles/.tool-versions

# Sur une nouvelle machine
cp ~/dotfiles/.tool-versions ~/.tool-versions
for plugin in $(cut -d' ' -f1 ~/.tool-versions); do
  asdf plugin add "$plugin"
done
asdf install

Déboguer les problèmes de version

asdf current indique non seulement la version retenue mais aussi le fichier qui l'a décidée, ce qui résout la majorité des cas où la mauvaise version est active.

# Voir quelle version est utilisée et pourquoi
asdf current nodejs
# → nodejs 22.13.1 /home/user/projet/.tool-versions

# Voir où est installé un outil
asdf where nodejs 22.13.1
# → /home/user/.asdf/installs/nodejs/22.13.1

# Vérifier le shim
which node
# → /home/user/.asdf/shims/node

Migrer depuis d'autres gestionnaires

La migration se fait outil par outil, sans période de bascule risquée. Le principe reste identique : relever la version actuellement utilisée, la réinstaller sous asdf, puis retirer l'ancien gestionnaire du shell. Tant que les lignes de nvm ou pyenv subsistent dans votre .bashrc, elles placent leur propre répertoire avant les shims dans le PATH et court-circuitent asdf.

Depuis nvm (Node.js)

nvm réécrit le PATH à chaque changement de version : supprimer ses lignes du fichier de configuration du shell compte autant que supprimer ~/.nvm.

# 1. Exporter la version actuelle
node_version=$(node --version | sed 's/v//')

# 2. Installer le plugin asdf
asdf plugin add nodejs

# 3. Installer la même version
asdf install nodejs "$node_version"
asdf set --home nodejs "$node_version"

# 4. Désinstaller nvm
rm -rf ~/.nvm
# Supprimer les lignes nvm de ~/.bashrc ou ~/.zshrc

Depuis pyenv (Python)

Comme pyenv, asdf compile Python localement ; les dépendances de compilation listées dans la section dépannage restent donc indispensables.

# 1. Exporter la version actuelle
python_version=$(python --version | cut -d' ' -f2)

# 2. Installer le plugin asdf
asdf plugin add python

# 3. Installer la même version
asdf install python "$python_version"
asdf set --home python "$python_version"

# 4. Désinstaller pyenv
rm -rf ~/.pyenv
# Supprimer les lignes pyenv de ~/.bashrc ou ~/.zshrc

Plugins populaires DevOps

Voici les plugins que l'on croise le plus souvent dans une configuration DevOps. Ils s'ajoutent tous de la même façon et sont référencés par le dépôt d'index asdf-plugins, qui ne fait que pointer vers le dépôt Git réel de chaque plugin. Vérifiez cette origine avant d'ajouter un plugin : son code s'exécutera sur votre machine avec vos droits.

Plugin	Commande d'installation	Usage
nodejs	asdf plugin add nodejs	Runtime JavaScript
python	asdf plugin add python	Scripting, ML, automation
golang	asdf plugin add golang	CLI tools, microservices
terraform	asdf plugin add terraform	Infrastructure as Code
kubectl	asdf plugin add kubectl	Gestion Kubernetes
helm	asdf plugin add helm	Charts Kubernetes
awscli	asdf plugin add awscli	CLI Amazon Web Services
gcloud	asdf plugin add gcloud	CLI Google Cloud

Glissez pour voir

Liste complète des plugins

Consultez asdf-plugins pour la liste des 700+ plugins disponibles. Vous pouvez aussi créer vos propres plugins.

Dépannage

La plupart des incidents avec asdf viennent du PATH ou d'un plugin périmé, rarement d'asdf lui-même. Le premier réflexe consiste à vérifier que ~/.asdf/shims figure bien dans le PATH et qu'il y arrive avant les répertoires système comme /usr/bin.

Le shim ne trouve pas la bonne version

asdf reshim recrée les scripts intermédiaires ; l'opération est nécessaire après l'installation d'un paquet qui pose ses propres exécutables, par exemple un npm install -g.

# Régénérer les shims
asdf reshim

# Vérifier que les shims sont dans le PATH
echo $PATH | tr ':' '\n' | grep asdf

Erreur "No version set for command"

Ce message signale qu'aucun .tool-versions applicable ne mentionne l'outil : définissez une version globale, qui servira de valeur de repli.

# Définir une version globale par défaut
asdf set --home nodejs latest

Plugin qui ne se met pas à jour

Un plugin est un dépôt Git : quand sa mise à jour échoue, le retirer puis le rajouter le reclone proprement, sans toucher aux versions déjà installées.

# Erreur courante avec nodejs
# /home/bob/.asdf/plugins/nodejs/bin/../lib/utils.sh: line 27: HOME: unbound variable

# Solution : mettre à jour le plugin manuellement
asdf plugin remove nodejs
asdf plugin add nodejs

Problème de dépendances (Python, Ruby)

Certains plugins nécessitent des dépendances système :

# Pour Python (compilation)
sudo apt install build-essential libssl-dev zlib1g-dev \
  libbz2-dev libreadline-dev libsqlite3-dev libffi-dev

# Pour Ruby
sudo apt install autoconf bison build-essential libssl-dev \
  libyaml-dev libreadline-dev zlib1g-dev libncurses5-dev

Sécurité : n'utilisez pas asdf en CI/CD

Les plugins asdf exécutent des scripts shell de sources tierces. Dans un pipeline CI/CD, cela représente un risque pour votre supply chain. Préférez :

• Images Docker avec les versions préinstallées
• Gestionnaires natifs du système (apt, apk)
• Binaires téléchargés avec vérification de checksum

Voir Sécuriser votre supply chain pour plus de détails.

À retenir

Concept	Commande / Fichier
Ajouter un plugin	asdf plugin add <nom>
Installer une version	asdf install <nom> <version>
Version globale	asdf set --home <nom> <version>
Version locale (projet)	asdf set <nom> <version>
Fichier de config	.tool-versions
Voir la version active	asdf current

Glissez pour voir

Points clés :

• Un seul outil pour gérer tous vos runtimes et outils CLI
• Le fichier .tool-versions synchronise toute l'équipe
• Priorité : local > parent > global
• Ne pas utiliser en CI/CD pour des raisons de sécurité

Prochaines étapes

mise : l'alternative moderne Gestionnaire de versions plus rapide et compatible asdf

direnv : variables par projet Chargez automatiquement vos variables d'environnement

Homebrew : gestionnaire de paquets Installez vos outils système avec brew

Sécuriser la supply chain Bonnes pratiques pour sécuriser vos dépendances

Ressources

Les sources officielles à consulter pour approfondir et suivre les évolutions d'asdf.

• Site officiel asdf
• Documentation asdf
• Liste des plugins
• Dépôt GitHub asdf

×

📖 Voir la documentation →