Débuter avec jq sous Linux pour manipuler du JSON

Quand on débute sous Linux, on rencontre vite des fichiers ou des réponses d’API au format JSON. Ce format est lisible par une machine, mais il devient vite pénible à parcourir à l’œil nu dès qu’il contient plusieurs niveaux, des tableaux, ou des dizaines de champs. C’est précisément le rôle de jq : permettre de lire, filtrer et transformer du JSON directement en ligne de commande.

Ce tutoriel s’adresse aux débutants. Il montre d’abord comment installer jq et l’utiliser sur de petits fichiers locaux, puis comment écrire des filtres simples pour extraire une valeur, parcourir une liste, sélectionner certains éléments et reconstruire un nouveau JSON. Chaque étape s’appuie sur des exemples concrets que vous pouvez recopier, tester, puis adapter à vos propres fichiers.

L’objectif n’est pas de couvrir toutes les possibilités de jq, mais de vous donner une base solide pour travailler sereinement avec des données JSON sous Linux. À la fin, vous saurez non seulement lire un fichier JSON, mais aussi produire des sorties plus utiles pour l’administration, l’automatisation et les petits scripts shell.

Prérequis

• Savoir ouvrir un terminal Linux.
• Connaître les commandes de base comme cd, ls et cat.
• Avoir les droits nécessaires pour installer un paquet sur votre machine si jq n’est pas déjà présent.
• Disposer de petits fichiers JSON de test, ou créer ceux fournis dans ce tutoriel.

Matériel nécessaire

• Un système Linux avec un terminal
• L’outil jq installé
• Des fichiers JSON d’exemple

Étapes

1. 1

   Comprendre ce que fait jq et pourquoi il est utile

   

   jq est un outil en ligne de commande conçu pour manipuler du JSON. On peut le voir comme un filtre : il lit un document JSON en entrée, applique une expression, puis renvoie un résultat. Cette idée est simple, mais très puissante, car elle s’intègre naturellement dans la philosophie Unix : lire depuis un fichier, depuis l’entrée standard, puis enchaîner des commandes.

   Dans la pratique, jq est utile dans plusieurs cas courants :

   • afficher un JSON de façon plus lisible ;
   • extraire une valeur précise dans un gros document ;
   • parcourir un tableau d’objets ;
   • sélectionner seulement certains éléments ;
   • reconstruire un nouveau JSON avec les champs qui vous intéressent.

   Exemple minimal :

   bash

   echo '{"nom":"serveur1","etat":"ok"}' | jq '.'

   Ici, le filtre . signifie simplement : « prends l’entrée JSON telle quelle ». L’intérêt n’est pas encore dans la transformation, mais dans l’affichage formaté. jq réindente alors proprement le document.

   Résultat attendu :

   bash

   {
     "nom": "serveur1",
     "etat": "ok"
   }

   Gardez en tête cette idée fondamentale : dans jq, on part souvent de ., qui représente l’objet ou la valeur en cours de traitement. Ensuite, on affine avec des accès à des clés, à des index de tableau, à des filtres, ou à des constructions de nouveaux objets.

2. 2

   Installer jq sur Linux et vérifier qu’il fonctionne

   

   Avant de manipuler des fichiers JSON, vérifiez si jq est déjà présent :

   bash

   jq --version

   Si la commande renvoie une version, vous pouvez continuer. Sinon, installez jq avec le gestionnaire de paquets de votre distribution.

   Sur Debian, Ubuntu, Linux Mint et systèmes proches :

   bash

   sudo apt update
   sudo apt install jq

   Sur Fedora :

   bash

   sudo dnf install jq

   Sur RHEL, CentOS Stream ou systèmes compatibles qui utilisent dnf :

   bash

   sudo dnf install jq

   Sur Arch Linux :

   bash

   sudo pacman -S jq

   Une fois l’installation terminée, revérifiez :

   bash

   jq --version

   Vous devez obtenir une sortie contenant le nom de l’outil et sa version. Ce contrôle simple évite de perdre du temps ensuite en débogage.

   À ce stade, retenez un point pratique : jq peut lire des données depuis un fichier, mais aussi depuis un pipe. Cela veut dire que vous pourrez l’utiliser aussi bien avec cat fichier.json | jq ... qu’avec jq ... fichier.json. Dans la plupart des cas, la seconde forme est plus directe.

3. 3

   Créer un premier fichier JSON de test

   

   Pour apprendre sans dépendre d’un service externe, commencez avec un petit fichier local. Créez un répertoire de travail, puis un fichier nommé serveur.json.

   bash

   mkdir -p ~/jq-demo
   cd ~/jq-demo

   Créez ensuite le fichier avec le contenu suivant :

   bash

   cat > serveur.json <<'EOF'
   {
     "nom": "web-01",
     "os": "linux",
     "cpu": 4,
     "memoire_gb": 8,
     "actif": true,
     "services": [
       "nginx",
       "ssh",
       "cron"
     ]
   }
   EOF

   Affichez le fichier :

   bash

   cat serveur.json

   Puis demandez à jq de le reformater :

   bash

   jq '.' serveur.json

   Cette première commande est importante, car elle sert aussi de test de validité : si le JSON est mal formé, jq renverra une erreur. C’est donc un bon réflexe quand on récupère un fichier incertain ou généré par un script.

   Dans cet exemple, le document contient plusieurs types JSON courants :

   • des chaînes de caractères, comme "web-01" ;
   • des nombres, comme 4 et 8 ;
   • un booléen, ici true ;
   • un tableau, ici la liste services ;
   • un objet JSON global, délimité par des accolades.

   Comprendre ces types aide à écrire les bons filtres ensuite.

4. 4

   Lire des clés simples dans un objet JSON

   Le cas le plus simple consiste à lire la valeur d’une clé. Avec jq, on utilise la notation .cle.

   bash

   jq '.nom' serveur.json

   Sortie attendue :

   bash

   "web-01"

   Autres exemples :

   bash

   jq '.os' serveur.json
   jq '.cpu' serveur.json
   jq '.actif' serveur.json

   Par défaut, jq renvoie les chaînes avec des guillemets, car la sortie reste du JSON valide. Si vous voulez une sortie texte plus pratique dans un script shell, utilisez l’option -r pour obtenir la valeur « brute ».

   bash

   jq -r '.nom' serveur.json

   Résultat :

   bash

   web-01

   Cette différence est essentielle :

   • jq '.nom' produit du JSON ;
   • jq -r '.nom' produit une chaîne simple, plus facile à réutiliser dans un shell.

   Vous pouvez aussi demander plusieurs champs à la fois :

   bash

   jq '.nom, .os, .cpu' serveur.json

   jq renverra alors plusieurs résultats successifs. C’est très utile pour explorer rapidement un document, mais si vous voulez une structure finale unique, il faudra reconstruire un objet ou un tableau, ce que nous verrons plus loin.

5. 5

   Parcourir un tableau JSON

   Le champ services de notre fichier est un tableau. Pour l’afficher en entier :

   bash

   jq '.services' serveur.json

   Pour accéder à un élément par son index, utilisez les crochets :

   bash

   jq '.services[0]' serveur.json

   Dans cet exemple, l’index 0 correspond au premier élément. Vous pouvez aussi afficher chaque service sur une ligne :

   bash

   jq '.services[]' serveur.json

   Avec l’option -r :

   bash

   jq -r '.services[]' serveur.json

   Vous obtenez alors une sortie très pratique :

   bash

   nginx
   ssh
   cron

   La notation [] est centrale dans jq. Elle signifie en pratique : « prends chaque élément du tableau ». Ensuite, vous pouvez continuer à chaîner d’autres filtres derrière cette étape.

   Par exemple, si un tableau contient des objets, on peut écrire un filtre du type .tableau[] .champ. Nous allons justement passer à ce cas avec un fichier plus réaliste.

6. 6

   Travailler avec un tableau d’objets : exemple concret d’inventaire

   Créons maintenant un fichier un peu plus proche d’un cas réel d’administration ou d’automatisation : une liste de machines. Créez inventaire.json avec ce contenu :

   bash

   cat > inventaire.json <<'EOF'
   [
     {
       "nom": "web-01",
       "role": "web",
       "os": "linux",
       "ip": "192.168.1.10",
       "actif": true
     },
     {
       "nom": "db-01",
       "role": "base",
       "os": "linux",
       "ip": "192.168.1.20",
       "actif": true
     },
     {
       "nom": "backup-01",
       "role": "sauvegarde",
       "os": "linux",
       "ip": "192.168.1.30",
       "actif": false
     }
   ]
   EOF

   Affichez le fichier :

   bash

   jq '.' inventaire.json

   Pour afficher chaque objet séparément :

   bash

   jq '.[]' inventaire.json

   Pour ne sortir que les noms :

   bash

   jq -r '.[].nom' inventaire.json

   Résultat :

   bash

   web-01
   db-01
   backup-01

   Décomposons cette expression :

   • . représente le tableau global ;
   • [] parcourt chaque élément du tableau ;
   • .nom extrait la clé nom de chaque objet.

   C’est l’un des schémas les plus fréquents avec jq : .[].champ. Vous le retrouverez très souvent avec des exports, des inventaires, des journaux structurés ou des réponses d’API.

7. 7

   Filtrer des éléments selon une condition

   Lire tout un tableau est utile, mais on veut souvent ne garder que certains éléments. Pour cela, jq propose la fonction select(...).

   Par exemple, pour n’afficher que les machines actives :

   bash

   jq '.[] | select(.actif == true)' inventaire.json

   Pour ne sortir que leurs noms :

   bash

   jq -r '.[] | select(.actif == true) | .nom' inventaire.json

   Résultat :

   bash

   web-01
   db-01

   On peut aussi filtrer par rôle :

   bash

   jq '.[] | select(.role == "web")' inventaire.json

   Ou ne sortir que l’adresse IP de la machine de base :

   bash

   jq -r '.[] | select(.role == "base") | .ip' inventaire.json

   Le caractère | représente un chaînage. Il signifie qu’on prend le résultat de gauche et qu’on l’envoie à l’étape suivante. Dans l’exemple précédent :

   1. on parcourt chaque élément avec .[] ;
   2. on garde seulement ceux qui respectent la condition avec select(...) ;
   3. on extrait enfin le champ souhaité.

   Ce mode de pensée est la clé pour progresser avec jq : au lieu de chercher une formule compliquée d’un seul bloc, découpez votre intention en petites étapes enchaînées.

8. 8

   Construire une sortie plus lisible pour un humain

   Les résultats JSON sont parfaits pour des échanges entre programmes, mais parfois on veut juste une sortie simple à lire dans le terminal. jq permet de produire du texte brut avec -r, mais aussi de combiner plusieurs champs dans un tableau ou un objet réduit.

   Exemple : afficher nom et IP pour chaque machine.

   bash

   jq '.[] | {nom: .nom, ip: .ip}' inventaire.json

   Résultat : chaque élément de sortie est un petit objet JSON ne contenant que deux clés.

   Si vous voulez un tableau final unique de ces objets réduits :

   bash

   jq '[.[] | {nom: .nom, ip: .ip}]' inventaire.json

   Cette différence est importante :

   • sans les crochets externes, jq émet plusieurs objets successifs ;
   • avec les crochets externes, jq reconstruit un tableau contenant tous ces objets.

   Vous pouvez aussi produire une ligne texte compacte :

   bash

   jq -r '.[] | .nom + " " + .ip' inventaire.json

   Sortie :

   bash

   web-01 192.168.1.10
   db-01 192.168.1.20
   backup-01 192.168.1.30

   Ce format est pratique pour l’œil humain, mais gardez à l’esprit qu’il ne s’agit plus de JSON. Si le résultat doit être réutilisé par un autre outil qui attend du JSON, restez sur une structure JSON propre.

9. 9

   Transformer un JSON : renommer, réorganiser, simplifier

   L’un des usages les plus utiles de jq est la transformation. Au lieu de simplement extraire des champs, on peut produire un nouveau document avec une structure différente.

   Reprenons inventaire.json. Supposons que vous vouliez un résultat avec les clés machine, adresse et en_service.

   bash

   jq '[.[] | {
     machine: .nom,
     adresse: .ip,
     en_service: .actif
   }]' inventaire.json

   Cette commande ne modifie pas le fichier source : elle lit le JSON, fabrique une nouvelle structure et l’affiche en sortie standard.

   Vous pouvez rediriger le résultat dans un nouveau fichier :

   bash

   jq '[.[] | {machine: .nom, adresse: .ip, en_service: .actif}]' inventaire.json > inventaire-simple.json

   Autre exemple concret : ne garder que les machines actives et seulement quelques informations.

   bash

   jq '[.[] | select(.actif == true) | {nom: .nom, role: .role, ip: .ip}]' inventaire.json

   Vous obtenez ainsi un tableau final plus petit, prêt à être partagé ou traité ailleurs.

   Cette manière de « projeter » un gros JSON vers une structure plus simple est très fréquente lorsqu’on manipule des exports verbeux ou des réponses d’API contenant beaucoup de champs inutiles pour la tâche du moment.

10. 10

    Travailler avec des objets imbriqués et des tableaux plus complexes

    Pour progresser, il faut aussi voir un exemple avec plusieurs niveaux. Créez un fichier utilisateurs.json :

    bash

    cat > utilisateurs.json <<'EOF'
    [
      {
        "nom": "Alice",
        "equipe": "infra",
        "contacts": {
          "email": "[email protected]",
          "ville": "Paris"
        },
        "outils": ["ssh", "ansible", "docker"]
      },
      {
        "nom": "Bruno",
        "equipe": "support",
        "contacts": {
          "email": "[email protected]",
          "ville": "Lyon"
        },
        "outils": ["ssh", "tmux"]
      }
    ]
    EOF

    Pour extraire les adresses e-mail :

    bash

    jq -r '.[].contacts.email' utilisateurs.json

    Pour afficher tous les outils de tous les utilisateurs :

    bash

    jq -r '.[].outils[]' utilisateurs.json

    Pour produire un résumé par personne :

    bash

    jq '[.[] | {nom: .nom, ville: .contacts.ville}]' utilisateurs.json

    Vous voyez ici que les accès peuvent se chaîner naturellement : .contacts.email signifie simplement « dans l’objet courant, va dans la clé contacts, puis dans la clé email ».

    De même, on peut entrer dans un tableau puis continuer le traitement. La logique est toujours la même : chaque filtre prend une entrée et produit une sortie sur laquelle le filtre suivant peut travailler.

11. 11

    Sélectionner selon le contenu d’un tableau

    Il est fréquent de vouloir garder uniquement les objets dont un tableau contient une certaine valeur. Avec notre fichier utilisateurs.json, imaginons que l’on cherche les personnes utilisant docker.

    bash

    jq '.[] | select(.outils[] == "docker")' utilisateurs.json

    Pour n’afficher que le nom :

    bash

    jq -r '.[] | select(.outils[] == "docker") | .nom' utilisateurs.json

    Résultat attendu :

    bash

    Alice

    Cette commande reste lisible si on l’aborde en étapes :

    • on parcourt les utilisateurs ;
    • on teste les valeurs du tableau outils ;
    • on conserve les objets correspondant au critère ;
    • on extrait le champ final voulu.

    Dans vos propres fichiers, ce modèle est très utile pour repérer des machines ayant un service donné, des utilisateurs ayant un rôle particulier, ou des éléments marqués par une étiquette spécifique.

12. 12

    Compter, regrouper visuellement et préparer une sortie exploitable

    Même en restant sur des bases de débutant, jq peut déjà servir à résumer des données. Sans entrer dans des constructions avancées, vous pouvez par exemple compter le nombre d’éléments d’un tableau avec length.

    bash

    jq 'length' inventaire.json

    Résultat attendu :

    bash

    3

    Compter le nombre de services dans serveur.json :

    bash

    jq '.services | length' serveur.json

    Compter le nombre de machines actives :

    bash

    jq '[.[] | select(.actif == true)] | length' inventaire.json

    Cette expression suit une logique simple :

    1. on parcourt les éléments ;
    2. on garde seulement ceux qui sont actifs ;
    3. on reconstruit un tableau avec les résultats ;
    4. on calcule sa longueur.

    Vous pouvez ensuite produire un petit rapport JSON :

    bash

    jq '{
      total: length,
      actives: [.[] | select(.actif == true)] | length
    }' inventaire.json

    Le résultat est un objet synthétique, très pratique pour un script ou une vérification rapide. Cette approche montre bien que jq ne sert pas uniquement à lire : il permet aussi de fabriquer une sortie structurée adaptée à un besoin précis.

13. 13

    Lire un JSON depuis un pipe et l’intégrer à des commandes Linux

    jq devient particulièrement utile lorsqu’il est utilisé dans un pipeline. Vous n’êtes pas limité aux fichiers : toute commande qui écrit du JSON sur sa sortie standard peut être suivie par jq.

    Exemple simple avec echo :

    bash

    echo '[{"nom":"web-01"},{"nom":"db-01"}]' | jq -r '.[].nom'

    Vous pouvez aussi lire un fichier avec cat, même si cela n’est pas indispensable :

    bash

    cat inventaire.json | jq -r '.[].ip'

    Dans la plupart des cas, la forme suivante est plus simple :

    bash

    jq -r '.[].ip' inventaire.json

    L’intérêt du pipe apparaît surtout quand une commande précédente génère elle-même le JSON. Vous pourrez alors insérer jq au bon endroit pour extraire exactement ce qui vous intéresse.

    Dans un script shell, l’option -r est souvent le bon choix quand vous voulez récupérer une valeur texte et la stocker dans une variable. À l’inverse, si le résultat doit rester du JSON pour être transmis plus loin, conservez la sortie JSON standard.

14. 14

    Enregistrer le résultat d’une transformation dans un nouveau fichier

    jq n’édite pas automatiquement le fichier source. Il affiche son résultat, et c’est à vous de décider quoi en faire. Le plus simple est souvent de rediriger la sortie vers un nouveau fichier.

    Exemple : créer une version réduite de l’inventaire contenant seulement les noms et IP des machines actives.

    bash

    jq '[.[] | select(.actif == true) | {nom: .nom, ip: .ip}]' inventaire.json > inventaire-actif.json

    Vérifiez ensuite le résultat :

    bash

    jq '.' inventaire-actif.json

    Cette méthode a plusieurs avantages :

    • le fichier d’origine reste intact ;
    • vous pouvez comparer l’entrée et la sortie ;
    • vous gardez une trace claire de la transformation appliquée.

    Quand on débute, il est préférable d’adopter cette habitude plutôt que d’essayer de remplacer un fichier « sur place ». Cela limite les erreurs et rend vos manipulations plus sûres.

15. 15

    Méthode de lecture d’un filtre jq pour ne pas se perdre

    Beaucoup de débutants trouvent jq intimidant non pas à cause des concepts, mais parce que les filtres semblent compacts. Une bonne méthode consiste à les lire de gauche à droite comme une suite d’étapes.

    Prenons ce filtre :

    bash

    [.[] | select(.actif == true) | {nom: .nom, ip: .ip}]

    On peut le traduire ainsi :

    1. partir du tableau d’entrée ;
    2. prendre chaque élément avec .[] ;
    3. ne garder que ceux dont actif vaut true ;
    4. pour chaque élément restant, construire un nouvel objet avec nom et ip ;
    5. mettre tous ces objets dans un tableau final grâce aux crochets externes.

    Cette façon de raisonner simplifie énormément la compréhension. Si un filtre ne fonctionne pas, testez-le par morceaux. Par exemple :

    bash

    jq '.[]' inventaire.json
    jq '.[] | select(.actif == true)' inventaire.json
    jq '.[] | select(.actif == true) | {nom: .nom, ip: .ip}' inventaire.json

    En observant le résultat à chaque étape, vous repérez plus facilement l’endroit où vous vous trompez sur la structure du JSON ou sur le comportement attendu.

Erreurs fréquentes & dépannage

Erreurs fréquentes avec jq

• Oublier de valider la structure JSON : si le fichier est mal formé, jq échouera. Commencez souvent par jq '.' fichier.json.
• Confondre objet et tableau : .nom s’applique à un objet, tandis que .[] sert à parcourir un tableau.
• Oublier l’option -r pour une sortie texte : sans elle, les chaînes sont renvoyées comme du JSON avec des guillemets.
• Penser que jq modifie le fichier source : jq affiche un résultat, mais ne remplace pas automatiquement le contenu du fichier d’entrée.
• Essayer d’écrire un filtre trop complexe d’un coup : il vaut mieux tester d’abord l’accès simple, puis le parcours, puis le filtrage, puis la transformation.
• Mal lire le chemin d’accès aux données : dans un objet imbriqué, vérifiez précisément à quel niveau se trouvent les clés et les tableaux.

Astuces & pour aller plus loin

Astuces pratiques

• Utilisez jq '.' fichier.json comme réflexe de départ pour reformater et vérifier rapidement un document JSON.
• Gardez en tête que . représente la valeur courante en cours de traitement.
• Commencez vos essais avec de petits fichiers locaux avant de traiter des réponses JSON plus volumineuses.
• Ajoutez -r quand vous voulez une sortie simple à réutiliser dans un shell.
• Si vous voulez un tableau final, entourez votre pipeline de crochets : [...].
• Déboguez vos filtres par étapes au lieu d’écrire directement une expression longue et compacte.

Questions fréquentes

À quoi sert jq sous Linux ?

jq sert à lire, filtrer et transformer des données JSON en ligne de commande. Il permet par exemple d’extraire une clé, de parcourir un tableau, de sélectionner certains objets et de reconstruire une nouvelle sortie JSON.

Quelle est la différence entre jq '.nom' et jq -r '.nom' ?

Sans -r, jq renvoie une valeur JSON, donc une chaîne apparaît avec des guillemets. Avec -r, jq renvoie une sortie texte brute, souvent plus pratique dans un terminal ou un script shell.

Comment parcourir tous les éléments d’un tableau JSON ?

On utilise la notation []. Par exemple, jq '.[].nom' inventaire.json parcourt chaque objet du tableau puis extrait la clé nom.

Comment filtrer seulement certains éléments ?

On peut utiliser select(...). Par exemple, jq '.[] | select(.actif == true)' inventaire.json ne garde que les objets dont la clé actif vaut true.

jq modifie-t-il directement le fichier JSON ?

Non. jq lit le JSON, applique un filtre puis écrit le résultat en sortie standard. Pour conserver le résultat, il faut le rediriger vers un nouveau fichier.

Comment créer un nouveau JSON avec seulement quelques champs ?

Il suffit de construire un objet avec les clés voulues, par exemple jq '[.[] | {nom: .nom, ip: .ip}]' inventaire.json. Cette commande reconstruit un tableau d’objets plus simples.

Conclusion

jq est un excellent outil pour débuter la manipulation de JSON sous Linux, car il permet de faire beaucoup avec quelques idées simples : . pour désigner la valeur courante, .cle pour lire une clé, [] pour parcourir un tableau, select(...) pour filtrer, et la construction d’objets pour transformer les données.

Dans ce tutoriel, vous avez vu comment installer jq, valider un fichier JSON, extraire des champs simples, parcourir des tableaux, filtrer des objets selon une condition, compter des éléments et reconstruire une sortie JSON adaptée à un besoin concret. Vous avez aussi vu comment intégrer jq dans des pipelines Linux et enregistrer le résultat dans un nouveau fichier.

Le plus important, pour progresser, est de raisonner par étapes. Commencez par afficher le JSON, repérez sa structure, testez un accès simple, puis ajoutez progressivement le parcours, le filtrage et la transformation. Avec cette méthode, jq devient vite un allié très efficace pour l’exploration de données, l’automatisation et les scripts shell du quotidien.