jq: JSON im Terminal lesen, filtern und umbauen
jq mit getesteten Beispielen: JSON formatieren, Felder lesen, mit select und map filtern, CSV exportieren und GitHub- oder Docker-Daten auswerten.
Von Nathan Base
Eine API liefert eine Wand aus Klammern, docker inspect spuckt 200 Zeilen aus, und Du suchst darin genau einen Wert. Für solche Fälle gibt es jq: ein kleines Kommandozeilenprogramm, das JSON lesbar formatiert, einzelne Felder herauszieht, Listen filtert und die Daten in eine neue Form bringt. Einmal verstanden, ersetzt es viele Zeilen Python für Dinge, die eigentlich nur ein Einzeiler sein sollten.
Alle Beispiele unten habe ich mit jq 1.7.1 auf macOS 27 ausgeführt, die gezeigten Ausgaben stammen aus diesen Läufen. Debian 13 Trixie installiert aus seinen Paketquellen ebenfalls jq 1.7. Die Filter nutzen nur Grundfunktionen, die es auch in der aktuellen Version 1.8 gibt.
jq installieren
Auf dem Mac ist jq seit macOS Sequoia bereits vorinstalliert. Prüf das im Terminal mit:
jq --versionErscheint jq-1.7.1-apple oder eine neuere Nummer, kannst Du direkt loslegen. Möchtest Du die aktuelle Version, installierst Du sie mit Homebrew. Falls Homebrew noch fehlt, hilft Dir die Anleitung Homebrew auf dem Mac installieren: Anleitung für macOS 27 weiter.
brew install jqUnter Debian, Ubuntu und Raspberry Pi OS kommt jq aus den Paketquellen:
sudo apt install jqDie Beispieldaten
Damit Du jeden Befehl selbst nachvollziehen kannst, arbeiten wir mit einer kleinen Datei. Lege sie mit nano geraete.json an, füge den Inhalt ein und speichere mit Strg + O, Enter und Strg + X:
{
"haus": "Wohnung",
"aktualisiert": "2026-11-17T09:00:00Z",
"geraete": [
{"name": "Router", "raum": "Flur", "watt": 9.8, "online": true, "tags": ["netz"]},
{"name": "NAS", "raum": "Keller", "watt": 21.5, "online": true, "tags": ["netz", "speicher"]},
{"name": "Fernseher", "raum": "Wohnzimmer", "watt": 0.4, "online": false, "tags": ["medien"]},
{"name": "Konsole", "raum": "Wohnzimmer", "watt": 11.2, "online": true, "tags": ["medien", "spiele"]}
]
}Das Prinzip von jq ist immer gleich: Du übergibst einen Filter in einfachen Anführungszeichen und die Datei. Statt einer Datei geht auch eine Pipe, etwa curl … | jq '.feld'.
Die zehn Muster, die Du ständig brauchst
1. Formatieren
Der einfachste Filter ist der Punkt. Er gibt die Eingabe unverändert, aber eingerückt und farbig aus:
jq . geraete.jsonDas ist oft schon alles, was Du willst, wenn eine API ihre Antwort in eine einzige Zeile quetscht. Den umgekehrten Weg, also alles kompakt in eine Zeile, gehst Du mit jq -c ..
2. Ein Feld lesen
Felder sprichst Du mit Punkt und Namen an, Ebenen hängst Du einfach an:
jq '.haus' geraete.jsonDie Ausgabe lautet "Wohnung", mit Anführungszeichen, weil jq gültiges JSON ausgibt. Für ein Element aus einer Liste schreibst Du den Index in eckige Klammern, gezählt wird ab null: jq '.geraete[0].name' geraete.json liefert "Router".
3. Rohausgabe mit -r
Willst Du den Wert in einem Shell-Skript weiterverwenden, stören die Anführungszeichen. Die Option -r (raw) lässt sie weg:
jq -r '.haus' geraete.jsonJetzt steht nur Wohnung da. Diese Option brauchst Du fast immer, wenn das Ergebnis in einer Variable landet, etwa status=$(jq -r '.status' antwort.json).
4. Über eine Liste laufen
Leere eckige Klammern bedeuten „jedes Element“. Damit holst Du alle Namen auf einmal:
jq -r '.geraete[].name' geraete.jsonDie Ausgabe sind vier Zeilen: Router, NAS, Fernseher, Konsole. Wie viele Einträge eine Liste hat, verrät jq '.geraete | length' geraete.json, hier 4. Der senkrechte Strich funktioniert wie in der Shell: Er reicht das Ergebnis des linken Filters an den rechten weiter.
5. Filtern mit select
select behält nur Elemente, für die eine Bedingung wahr ist. Alle Geräte über 10 Watt:
jq -r '.geraete[] | select(.watt > 10) | .name' geraete.jsonDas Ergebnis ist NAS und Konsole. Bedingungen kannst Du mit and und or verknüpfen. select(.raum == "Wohnzimmer" and .online) findet nur die Konsole, weil der Fernseher "online": false hat. Ob eine Liste einen bestimmten Wert enthält, prüfst Du mit index: select(.tags | index("medien")) liefert Fernseher und Konsole.
6. Werte sammeln mit map und add
map wendet einen Filter auf jedes Element einer Liste an und gibt wieder eine Liste zurück. add zählt die Werte zusammen:
jq '.geraete | map(.watt) | add' geraete.jsonHeraus kommt 42.9, die Summe aller Leistungen. Du kannst direkt weiterrechnen: jq '[.geraete[].watt] | add * 24 * 365 / 1000 | round' geraete.json ergibt 376, also rund 376 Kilowattstunden im Jahr, wenn alle Geräte durchlaufen.
7. Neue Objekte bauen
In geschweiften Klammern stellst Du Dir ein eigenes Objekt zusammen. Steht dort nur ein Feldname, übernimmt jq Name und Wert:
jq -c '[.geraete[] | {name, watt}]' geraete.jsonDie Ausgabe ist eine schlanke Liste: [{"name":"Router","watt":9.8},{"name":"NAS","watt":21.5},…]. Umbenennen geht mit {geraet: .name, leistung: .watt}. Für eine Summe pro Raum kombinierst Du group_by mit map:
jq -c '.geraete | group_by(.raum) | map({raum: .[0].raum, watt: (map(.watt) | add)})' geraete.jsonDas ergibt [{"raum":"Flur","watt":9.8},{"raum":"Keller","watt":21.5},{"raum":"Wohnzimmer","watt":11.6}].
8. Als CSV ausgeben
Für eine Tabellenkalkulation baust Du pro Element eine Liste und schickst sie durch @csv. Wichtig ist dabei -r, sonst landen zusätzliche Anführungszeichen in der Datei:
jq -r '.geraete[] | [.name, .raum, .watt] | @csv' geraete.json > geraete.csvIn der Datei stehen danach Zeilen wie "Router","Flur",9.8. Mit @tsv statt @csv bekommst Du tabulatorgetrennte Werte, die sich auch gut im Terminal lesen lassen. Einen lesbaren Satz baust Du mit String-Interpolation: jq -r '.geraete[] | "\(.name): \(.watt) W"' geraete.json liefert Router: 9.8 W und so weiter.
9. Variablen aus der Shell übergeben
Werte aus der Shell setzt Du nicht in den Filter hinein, sondern übergibst sie sauber als Variable. --arg übergibt Text, --argjson eine Zahl oder anderes JSON:
jq -r --arg raum Keller '.geraete[] | select(.raum == $raum) | .name' geraete.jsonDas liefert NAS. Mit --argjson grenze 5 und select(.watt < $grenze) findest Du entsprechend den Fernseher. Der Vorteil gegenüber zusammengeklebten Strings: Anführungszeichen oder Leerzeichen im Wert können den Filter nicht kaputt machen.
10. Werte ändern und löschen
jq kann JSON auch umschreiben. Mit = setzt Du einen Wert, mit |= veränderst Du ihn auf Basis des alten:
jq '.geraete[0].watt = 7.5' geraete.json > geraete-neu.jsonDer Befehl schreibt die komplette Datei mit dem geänderten Wert in eine neue Datei. jq ändert die Originaldatei nie selbst, und eine Umleitung auf dieselbe Datei (> geraete.json) würde sie leeren, bevor jq sie liest. Schreib deshalb in eine neue Datei und benenne sie danach mit mv geraete-neu.json geraete.json um. Ein Feld entfernst Du mit del(.aktualisiert), und .geraete |= map(.watt |= . * 2) verdoppelt alle Leistungswerte auf einmal.
Drei Beispiele aus der Praxis
GitHub-API: neueste Version eines Projekts
Viele Update-Skripte müssen wissen, welche Version gerade aktuell ist. Die GitHub-API liefert das ohne Anmeldung:
curl -s https://api.github.com/repos/jqlang/jq/releases/latest | jq -r '.tag_name'Als ich das geschrieben habe, kam jq-1.8.2 zurück. Ersetze jqlang/jq durch Besitzer und Namen eines beliebigen anderen öffentlichen Repositorys. Ohne Token erlaubt GitHub nur eine begrenzte Zahl von Anfragen pro Stunde, für gelegentliche Abfragen reicht das aber. Wie Du solche Aufrufe in größeren Skripten absicherst, zeigt der Artikel Robuste API-Aufrufe in Python: Timeouts, Retries, Logging.
docker inspect: Status und IP eines Containers
docker inspect gibt eine Liste mit einem großen Objekt aus. Mit jq greifst Du gezielt hinein:
docker inspect mein-container | jq -r '.[0].State.Status, .[0].NetworkSettings.Networks[].IPAddress'Ersetze mein-container durch den Namen aus docker ps. In meinem Test mit einem Nginx-Container kam running und 172.17.0.3 zurück. Das Komma im Filter gibt mehrere Werte nacheinander aus, und .Networks[] funktioniert unabhängig davon, wie das Netzwerk heißt, was gerade bei Compose-Projekten mit eigenen Netzen praktisch ist. Wie diese Netzwerke entstehen, erklärt Docker Compose verstehen: Volumes, Netzwerke und .env.
Home Assistant: Sensorwerte über die REST-API
Home Assistant beantwortet Abfragen über seine REST-API mit JSON. Dafür brauchst Du ein langlebiges Zugriffstoken, das Du in Home Assistant unter Profil > Sicherheit > Langlebige Zugriffstoken erstellst. Speichere es in einer Variable, damit es nicht in der Befehlshistorie auftaucht, wenn Du es später wiederverwendest:
read -s HA_TOKENFüge das Token ein und drücke Enter, die Eingabe bleibt unsichtbar. Danach listest Du alle Temperatursensoren mit Wert auf:
curl -s -H "Authorization: Bearer $HA_TOKEN" http://homeassistant.local:8123/api/states | jq -r '.[] | select(.attributes.device_class == "temperature") | "\(.entity_id): \(.state)"'Passe homeassistant.local an, falls Deine Instanz unter einer anderen Adresse läuft. Jede Zeile der Ausgabe zeigt eine Entität und ihren aktuellen Wert, etwa sensor.wohnzimmer_temperatur: 21.4. Einen einzelnen Wert holst Du über /api/states/sensor.wohnzimmer_temperatur und den Filter .state.
Wenn jq meckert
Die meisten Fehlermeldungen haben eine von drei Ursachen:
parse error: Invalid numeric literal: Die Eingabe ist gar kein JSON. Häufig liefertcurleine HTML-Fehlerseite oder eine Weiterleitung. Lass| jqeinmal weg und schau Dir an, was wirklich zurückkommt.Cannot index array with "name": Du hast ein Feld auf einer Liste aufgerufen. Setz[]oder einen Index davor, also.[].nameoder.[0].name.nullstatt eines Werts: Das Feld existiert an dieser Stelle nicht, oft wegen eines Tippfehlers oder einer anderen Groß- und Kleinschreibung. Mitjq 'keys' datei.jsonsiehst Du, welche Felder es auf der obersten Ebene gibt.
In Skripten hilft die Option -e: Dann beendet sich jq mit einem Fehlercode, wenn das Ergebnis null oder false ist, und Dein Skript kann darauf reagieren.
Wo es weitergeht
Mit diesen zehn Mustern kommst Du im Alltag sehr weit. Für alles Weitere, etwa reduce, reguläre Ausdrücke mit test oder Datumsfunktionen, ist das offizielle jq-Handbuch die beste Quelle, weil jede Funktion dort mit einem kleinen Beispiel steht. Ein guter Trick zum Ausprobieren: Hol Dir die Antwort einer API einmal als Datei mit curl -s … > antwort.json und bau Deinen Filter dann Schritt für Schritt an dieser Datei auf, statt die API bei jedem Versuch neu abzufragen.
Weiterlesen.
-
Selfhosting & WebRobuste API-Aufrufe in Python: Timeouts, Retries, Logging
Python-Skripte, die regelmäßig APIs abfragen, brechen bei Netzwerkfehlern gern ab. Timeouts, automatische Wiederholungen und Logging machen sie robust.
Nathan Base -
Apple MacHomebrew auf dem Mac installieren: Anleitung für macOS 27
Homebrew auf dem Mac installieren, den Pfad in der zsh einrichten und die wichtigsten brew-Befehle nutzen. Für Apple-Chip und Intel, mit Fehlerhilfe.
Nathan Base -
Selfhosting & WebDocker Compose verstehen: Volumes, Netzwerke und .env
Docker Compose verständlich erklärt: Named Volume oder Bind Mount, Dienstnamen als Hostnamen, .env-Variablen, Healthchecks, sichere Updates und Backups.
Nathan Base -
Selfhosting & WebSSH-Schlüssel erstellen: ed25519 Schritt für Schritt
SSH-Key mit ssh-keygen erzeugen, per ssh-copy-id auf Server und Pi bringen, bei GitHub hinterlegen und „Permission denied (publickey)“ lösen.
Nathan Base -
Selfhosting & WebDocker belegt zu viel Speicher: sicher aufräumen
Docker füllt die Platte? So findest Du mit docker system df die Ursache, räumst Images und Build-Cache sicher auf und begrenzt wachsende Container-Logs.
Nathan Base -
Selfhosting & WebUptime Kuma einrichten: Websites und Dienste überwachen
Uptime Kuma 2 mit Docker Compose installieren, Websites und SSL-Zertifikate überwachen, per ntfy oder Telegram alarmieren und eine Statusseite anlegen.
Nathan Base