yq — YAML und JSON auf der Kommandozeile verarbeiten

yq ist ein schlanker Kommandozeilen-Prozessor für strukturierte Daten – wie jq, nur in erster Linie für YAML (und obendrein für JSON, XML, CSV, TOML und Properties). Achte darauf, welches yq du installiert hast: Dieser Guide bezieht sich auf das in Go geschriebene mikefarah/yq mit seiner eigenen, jq-ähnlichen Ausdruckssyntax (yq eval, yq '.foo', -i für In-Place-Bearbeitung, -o=json für die Ausgabe). Das ältere kislyuk/yq ist hingegen ein Python-Wrapper um jq und verwendet eine andere Syntax – die folgenden Beispiele funktionieren dort so nicht. Du fragst damit Werte ab, filterst Listen, änderst Dateien direkt und konvertierst zwischen Formaten, und das nahtlos in Pipelines mit Tools wie kubectl oder docker compose.

Lesen & Abfragen

yq <file> — Gibt eine YAML-Datei formatiert aus.

yq config.yaml

yq '.<key>' <file> — Liest einen bestimmten Schlüssel.

yq '.server.port' config.yaml

yq '.<key>.<nested>' <file> — Liest einen verschachtelten Wert.

yq '.database.connection.host' config.yaml

yq '.<array>[<n>]' <file> — Liest ein Array-Element über seinen Index.

yq '.services[0].name' docker-compose.yml

yq '.<array>[]' <file> — Iteriert über alle Array-Elemente.

yq '.users[].email' config.yaml

yq '.[] | key' <file> — Listet alle Schlüssel der obersten Ebene auf.

yq '.[] | key' config.yaml

Ändern & Aktualisieren

yq '.<key> = "<value>"' <file> — Setzt einen Wert (Ausgabe nach stdout).

yq '.server.port = 8080' config.yaml

yq -i '.<key> = "<value>"' <file> — Setzt einen Wert direkt in der Datei (In-Place).

yq -i '.version = "2.0.0"' config.yaml

yq '.<key> += "<value>"' <file> — Hängt einen Wert an ein Array an.

yq -i '.tags += ["new-tag"]' config.yaml

yq 'del(.<key>)' <file> — Löscht einen Schlüssel.

yq -i 'del(.deprecated_setting)' config.yaml

yq '.<key> |= . + 1' <file> — Erhöht einen numerischen Wert.

yq -i '.build_number |= . + 1' version.yaml

Filtern & Auswählen

yq '.[] | select(.<key> == "<value>")' <file> — Wählt Elemente aus, die eine Bedingung erfüllen.

yq '.users[] | select(.role == "admin")' users.yaml

yq '.[] | select(.<key> > <n>)' <file> — Wählt Elemente per numerischem Vergleich aus.

yq '.items[] | select(.price > 100)' catalog.yaml

yq '.<array> | length' <file> — Zählt die Elemente eines Arrays.

yq '.services | length' docker-compose.yml

yq '.[] | keys' <file> — Listet die Schlüssel einer Map auf.

yq '.services | keys' docker-compose.yml

yq 'has("<key>")' <file> — Prüft, ob ein Schlüssel existiert.

yq 'has("database")' config.yaml

Formatkonvertierung

yq -o=json <file> — Konvertiert YAML nach JSON.

yq -o=json config.yaml > config.json

yq -p=json <file> — Liest JSON ein und gibt YAML aus.

yq -p=json config.json > config.yaml

yq -p=json -o=yaml <file> — Konvertiert JSON nach YAML (explizit).

yq -p=json -o=yaml package.json

yq -o=xml <file> — Konvertiert YAML nach XML.

yq -o=xml config.yaml

yq -o=csv <file> — Konvertiert YAML nach CSV.

yq -o=csv '.users' data.yaml

yq -o=props <file> — Konvertiert YAML ins Java-Properties-Format.

yq -o=props config.yaml

Zusammenführen & Multi-Dokument

yq '. * load("<file>")' <base> — Führt zwei YAML-Dateien tief zusammen (die zweite überschreibt die erste).

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

yq eval-all '. as $item ireduce ({}; . * $item)' <file1> <file2> — Führt mehrere Dateien zusammen.

yq eval-all '. as $item ireduce ({}; . * $item)' defaults.yaml env.yaml

yq -s '"doc_" + $index' <file> — Teilt ein Multi-Dokument-YAML in einzelne Dateien auf.

yq -s '"doc_" + $index' multi.yaml

yq 'select(documentIndex == 0)' <file> — Wählt ein bestimmtes Dokument aus einem Multi-Dokument-YAML aus.

yq 'select(documentIndex == 0)' multi.yaml

Pipes & gängige Muster

cat <file> | yq '.<key>' — Liest von stdin.

kubectl get pod mypod -o yaml | yq '.metadata.labels'

yq -r '.<key>' <file> — Rohe Ausgabe (ohne Anführungszeichen um Strings).

yq -r '.image' deployment.yaml

yq -i '.image = "nginx:1.25"' deployment.yaml — Aktualisiert eine Container-Image-Version in einem Kubernetes-Manifest.

yq -i '.spec.template.spec.containers[0].image = "nginx:1.25"' deployment.yaml

yq '.env_file' docker-compose.yml — Inspiziert eine Docker-Compose-Konfiguration auf der Kommandozeile.

yq '.services.web.environment' docker-compose.yml

Fazit

yq macht das Lesen und Umbauen von YAML, JSON und Co. auf der Kommandozeile so bequem, wie jq es für JSON ist – ideal für Pipelines mit kubectl, docker compose oder CI-Skripten. Behalte aber im Kopf, dass alle hier gezeigten Beispiele für mikefarah/yq (Go) gelten; mit dem Python-Wrapper kislyuk/yq sehen viele Ausdrücke anders aus. Besondere Vorsicht ist bei -i (In-Place) geboten: yq überschreibt die Datei direkt und ohne Rückfrage – lege vorher ein Backup an oder arbeite unter Versionskontrolle, und teste neue Ausdrücke zuerst ohne -i, indem du die Ausgabe nach stdout prüfst. Beachte außerdem, dass yq beim In-Place-Bearbeiten Kommentare und Formatierung weitgehend erhält, die Datei aber dennoch normalisieren kann.

Weiterführende Links

mikefarah/yq – Dokumentation – offizielles Handbuch mit allen Operatoren und Beispielen (englisch)
mikefarah/yq auf GitHub – Quellcode, Installationsanleitung und Release-Notes (englisch)