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 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

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

Gérer les plugins

# 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

# 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

# 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
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

Mettre à jour tous vos outils en une commande

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

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

# 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

# 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

Depuis nvm (Node.js)

# 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)

# 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

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

Le shim ne trouve pas la bonne version

# 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”

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

Plugin qui ne se met pas à jour

# 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

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

×

📖 Voir la documentation →