Zum Inhalt springen
SONOYA.com
Selfhosting & Web

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

Symbol geschweifter Klammern als Zeichen für JSON-Daten, die mit jq im Terminal gefiltert werden

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:

Code
jq --version

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

Code
brew install jq

Unter Debian, Ubuntu und Raspberry Pi OS kommt jq aus den Paketquellen:

Code
sudo apt install jq

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

Code
{
  "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:

Code
jq . geraete.json

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

Code
jq '.haus' geraete.json

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

Code
jq -r '.haus' geraete.json

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

Code
jq -r '.geraete[].name' geraete.json

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

Code
jq -r '.geraete[] | select(.watt > 10) | .name' geraete.json

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

Code
jq '.geraete | map(.watt) | add' geraete.json

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

Code
jq -c '[.geraete[] | {name, watt}]' geraete.json

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

Code
jq -c '.geraete | group_by(.raum) | map({raum: .[0].raum, watt: (map(.watt) | add)})' geraete.json

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

Code
jq -r '.geraete[] | [.name, .raum, .watt] | @csv' geraete.json > geraete.csv

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

Code
jq -r --arg raum Keller '.geraete[] | select(.raum == $raum) | .name' geraete.json

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

Code
jq '.geraete[0].watt = 7.5' geraete.json > geraete-neu.json

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

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

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

Code
read -s HA_TOKEN

Füge das Token ein und drücke Enter, die Eingabe bleibt unsichtbar. Danach listest Du alle Temperatursensoren mit Wert auf:

Code
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 liefert curl eine HTML-Fehlerseite oder eine Weiterleitung. Lass | jq einmal 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 .[].name oder .[0].name.
  • null statt eines Werts: Das Feld existiert an dieser Stelle nicht, oft wegen eines Tippfehlers oder einer anderen Groß- und Kleinschreibung. Mit jq 'keys' datei.json siehst 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.