yq — Le processeur YAML que vous savez déjà utiliser

Vous avez un compose.yaml avec dix services. Vous voulez savoir quelle image utilise le service db sans ouvrir d'éditeur. Vous voulez incrémenter un numéro de version dans un fichier CI sans une one-liner sed que vous ne retiendrez jamais. Vous voulez extraire tous les noms de services dans une liste.

Ce sont des problèmes pour jq. Mais vos fichiers sont en YAML, pas en JSON.

Voici yq.

Ce qu'est yq — et lequel​

Il existe deux outils nommés yq. Cet article traite de yq de Mike Farah (Go, image Docker mikefarah/yq), qui gère nativement YAML et offre une syntaxe compatible jq. L'autre (kislyuk/yq) encapsule jq après avoir converti le YAML en JSON — idée similaire, comportement différent pour les fonctionnalités propres à YAML comme les commentaires et les fichiers multi-documents. Sur Debian et Ubuntu, apt install yq installe cet autre outil (kislyuk/yq 3.x), pas celui utilisé ici.

Si vous avez la version Go installée localement (yq --version renvoie quelque chose comme yq (https://github.com/mikefarah/yq/) version v4.x), tout est prêt. Sinon, l'approche Docker ci-dessous ne demande rien de plus.

Le voir à l'œuvre avec Docker​

Avant d'installer quoi que ce soit (ou même de mettre en place l'alias ci-dessous), essayez yq dans un container jetable — le compose.yaml exact de cet article s'y trouve déjà.

Buildez et lancez :

$ docker build -t yq-demo .
[+] Building 8.7s (7/7) FINISHED
✔ exporting to image
$ docker run --rm -it yq-demo
🐳 root ~/demo # yq '.services.web.image' compose.yaml
nginx:1.25

Même fichier, même query, même résultat — testez directement dessus le reste des sections « Lire des valeurs » et « Modifier sur place » ci-dessous, il n'y a plus rien à préparer.

Installer — ou juste créer un alias​

Un gestionnaire de packages installe la version Go sur toutes les plateformes :

$ brew install yq            # macOS and Linux (Homebrew)
$ winget install MikeFarah.yq  # Windows

Ne rien installer du tout est aussi une option : une petite fonction yq lance l'image officielle à la place, dans son propre fichier placé dans un dossier que votre shell charge au démarrage (l'organisation expliquée dans mon workflow ZSH modulaire) :

# yq: run mikefarah/yq through Docker on the files of the current folder, no
# local install. Works in zsh and bash: save it as ~/.zsh/fns/yq.zsh or
# ~/.bash/fns/yq.sh (see https://www.avonture.be/blog/linux-yq).
#
# Runs with your own user ID, so files edited in place with -i keep their owner.
# The image is pulled automatically the first time.
yq() {
    if ! command -v docker >/dev/null 2>&1; then?
        printf '\e[31mError: docker is not installed or not in your PATH.\e[0m\n' >&2?
        return 1
    fi

    docker run --rm -i \
        -u "$(id -u):$(id -g)" \?
        -v "${PWD}:/workdir" \?
        mikefarah/yq:4 "$@"?
}

Elle monte votre répertoire courant dans le container et exécute yq de façon transparente, avec votre propre ID utilisateur pour que les fichiers modifiés avec -i gardent leur propriétaire. Toutes les commandes yq ci-dessous fonctionnent avec elle telles quelles. Le code est identique pour zsh et bash ; seuls le dossier et le chargeur diffèrent.

for fn_file in ~/.zsh/fns/*.zsh; do
  source "$fn_file"
done

for fn_file in ~/.bash/fns/*.sh; do
  [[ -r "$fn_file" ]] && source "$fn_file"
done

Vérifiez que le shell connaît la fonction : type yq doit répondre yq is a shell function.

La page des releases propose aussi des binaires statiques pour Linux, macOS et Windows — sans aucune dépendance à l'exécution.

Lire des valeurs​

Travaillons avec un compose.yaml typique :

services:
  web:
    image: nginx:1.25
    ports:
      - "8080:80"?
    environment:
      APP_ENV: production
      LOG_LEVEL: info
    volumes:
      - ./html:/usr/share/nginx/html:ro?
    depends_on:?
      - db

  db:
    image: postgres:16
    environment:
      POSTGRES_USER: myapp
      POSTGRES_PASSWORD: s3cr3t
      POSTGRES_DB: myapp_db
    volumes:
      - db_data:/var/lib/postgresql/data?

volumes:
  db_data:

Lire une valeur unique :

yq '.services.web.image' compose.yaml

nginx:1.25

Lire une valeur imbriquée :

yq '.services.db.environment.POSTGRES_DB' compose.yaml

myapp_db

Lister tous les noms de services :

yq '.services | keys' compose.yaml

- web
- db

Récupérer toutes les images de tous les services :

yq '.services.*.image' compose.yaml

nginx:1.25
postgres:16

Filtrer et sélectionner​

Récupérer uniquement les services qui définissent une clé ports :

yq '.services | with_entries(select(.value | has("ports")))' compose.yaml

web:
  image: nginx:1.25
  ports:
    - "8080:80"
  ...

Lister tous les noms de variables d'environnement du service web :

yq '.services.web.environment | keys' compose.yaml

- APP_ENV
- LOG_LEVEL

Modifier sur place​

Mettre à jour la version de l'image web. Le flag -i modifie le fichier sur place, exactement comme sed -i :

yq -i '.services.web.image = "nginx:1.27"' compose.yaml

Ajouter une nouvelle variable d'environnement :

yq -i '.services.web.environment.DEBUG = "false"' compose.yaml

Supprimer une clé :

yq -i 'del(.services.db.environment.POSTGRES_PASSWORD)' compose.yaml

Lire depuis stdin et chaîner les commandes​

yq lit depuis stdin quand aucun fichier n'est fourni, ce qui facilite le chaînage avec d'autres commandes :

cat compose.yaml | yq '.services | keys'

Combinez-le avec curl pour parser des API ou des configs YAML téléchargées à la volée :

curl -s https://example.com/config.yaml | yq '.database.host'

Cas d'usage pratiques​

Extraire tous les mappings de ports​

yq '.services.*.ports[]' compose.yaml

8080:80

Vérifier qu'une clé existe avant de l'utiliser​

yq '.services | has("redis")' compose.yaml

false

Mettre à jour une version dans tout un fichier CI​

Pour un .gitlab-ci.yml qui référence une version d'image à plusieurs endroits, .. parcourt chaque nœud du fichier, quelle que soit sa profondeur :

yq -i '(.. | select(. == "node:20")) = "node:22"' .gitlab-ci.yml

Merger deux fichiers YAML​

yq '. *= load("overrides.yaml")' base.yaml

Cette commande fusionne en profondeur overrides.yaml dans base.yaml et affiche le résultat — les fichiers source restent inchangés, sauf si vous ajoutez -i.

Convertir du YAML en JSON​

Quand vous devez passer des données YAML à un outil qui n'accepte que du JSON :

yq -o json '.services.web' compose.yaml

{
  "image": "nginx:1.25",
  "ports": [
    "8080:80"
  ],
  "environment": {
    "APP_ENV": "production",
    "LOG_LEVEL": "info"
  },
  "volumes": [
    "./html:/usr/share/nginx/html:ro"
  ],
  "depends_on": [
    "db"
  ]
}

Vous pouvez ensuite envoyer cette sortie directement à jq pour la traiter davantage.

Le pont avec jq​

Si vous utilisez déjà jq pour JSON, la syntaxe de yq vous semblera immédiatement familière. Les expressions jq du quotidien fonctionnent telles quelles :

Les principales différences : yq ajoute -i pour les modifications sur place et -o pour le format de sortie, et gère les fonctionnalités natives de YAML comme les ancres et les fichiers multi-documents (séparateurs ---).

Conclusion​

yq comble le manque que tout utilisateur de jq finit par ressentir : le même outil, mais pour YAML. Avec un alias Docker, il n'y a rien à installer, et la syntaxe se transpose directement depuis tout ce que vous connaissez déjà. Si votre workflow implique des compose.yaml, GitLab CI, GitHub Actions ou des manifests Kubernetes, yq a sa place dans votre boîte à outils aux côtés de jq et de son équivalent XML, xmlstarlet.

La prochaine fois que vous ouvrirez un éditeur de texte pour vérifier une version d'image ou modifier une clé de configuration, utilisez plutôt yq.