jq : manipuler du JSON depuis le terminal facilement

Vous ouvrez un fichier JSON dans le terminal. Des accolades partout, des tableaux imbriqués, des clés à rallonge… et très vite, cette simple donnée devient illisible. Pourtant, ce JSON contient exactement l’information que vous cherchez. C’est précisément là que jq change la donne. Cet outil permet de lire, filtrer, transformer et analyser du JSON directement depuis le terminal, avec une syntaxe concise et étonnamment puissante.

• Comprendre comment exploiter des fichiers JSON directement depuis le terminal Ave jq, sans écrire de script complexe ni dépendre d’outils externes.
• Gagner en autonomie et en efficacité pour analyser, filtrer et transformer des données issues d’APIs ou de fichiers JSON.
• Développer des réflexes pratiques pour intégrer jq dans vos commandes et automatisations, et gagner du temps dans vos workflows.

Avec jq, même sans être un expert en ligne de commande, vous pouvez rapidement faire des choses très avancées dans la manipulation de JSON depuis le terminal.

Qu’est-ce que jq exactement ?

jq est un outil en ligne de commande spécialisé dans la manipulation de données JSON. On peut le voir comme l’équivalent de sed ou awk, mais dédié exclusivement au format JSON.

Concrètement, jq lit du JSON en entrée, applique une ou plusieurs transformations, puis renvoie du JSON (ou du texte) en sortie. Il ne modifie pas vos fichiers par défaut, il agit comme un filtre. Cette approche est extrêmement rassurante pour débuter, car on peut tester sans rien casser.

jq est open-source, multiplateforme, et largement utilisé dans les environnements Linux, macOS et les pipelines CI/CD. . Même pour un simple script local ou une inspection rapide de données, jq devient vite indispensable.

Pourquoi manipuler du JSON depuis le terminal ?

Le JSON est partout. APIs, fichiers de configuration, exports de bases de données, réponses HTTP, logs, outils cloud… Dès que vous travaillez un minimum avec le web ou des outils modernes, vous en croisez forcément.

La plupart du temps, vous pourriez ouvrir ces fichiers dans un éditeur graphique. Mais dès que les données deviennent volumineuses ou dynamiques, cette approche montre vite ses limites. Le terminal, lui, permet de chaîner des commandes, d’automatiser, de répéter et surtout d’aller droit au but.

Manipuler du JSON depuis le terminal permet par exemple d’extraire une valeur précise dans une réponse d’API, de filtrer une liste d’objets selon un critère, de transformer une structure pour l’exploiter ailleurs, ou encore de vérifier rapidement la forme d’un fichier avant traitement.

À quoi sert réellement jq dans la pratique ?

jq sert avant tout à lire intelligemment des données JSON. Mais il va bien plus loin que la simple lecture.

Il permet d’extraire une clé précise, de parcourir des tableaux, de filtrer des objets, de renommer des champs, de calculer des valeurs, de reformater des données, ou même de produire du texte exploitable par d’autres commandes du terminal.

Une fois que vous commencez à l’utiliser, vous réalisez que beaucoup de petits scripts deviennent inutiles. jq fait en une ligne ce qui aurait demandé plusieurs dizaines de lignes en JavaScript ou en PHP.

Installer jq sur votre machine

Avant de manipuler quoi que ce soit, il faut évidemment installer jq.

Sur macOS, l’installation est très simple via Homebrew. Une seule commande suffit, et jq est prêt à l’emploi. Sur Linux, la majorité des distributions proposent jq directement dans leurs dépôts officiels. Sous Windows, il est possible de l’utiliser via WSL ou en téléchargeant le binaire officiel.

Installer jq avec Homebrew sur macOS

Sur macOS, Homebrew permet d’installer jq en quelques secondes. Ouvrez votre terminal, puis exécutez simplement la commande suivante pour lancer l’installation :

brew install jq

Une fois l’installation terminée, vous pouvez vérifier que jq est bien disponible en affichant sa version :

jq --version

Si un numéro de version apparaît dans le terminal, jq est correctement installé et vous pouvez commencer à manipuler des fichiers JSON sans attendre.

Pour afficher la liste des commandes, tapez :

jq -h

Comprendre le principe de base de jq

jq fonctionne toujours selon le même schéma :

• Reçoit du JSON en entrée,
• applique un filtre,
• affiche le résultat.

La source du JSON peut être un fichier, le résultat d’une commande, ou même une chaîne de caractères. Le filtre, lui, indique à jq ce que vous voulez extraire ou transformer.

Prenons un exemple très simple. Imaginons un fichier user.json contenant des informations basiques sur un utilisateur. Ce fichier contient un objet avec un nom, un âge et une ville.

{"name":"Alice","age":30,"city":"Paris"}

La commande cat sert simplement à afficher le contenu brut du fichier user.json dans le terminal.

cat user.json

Elle ne modifie absolument rien. Elle lit le fichier tel qu’il est stocké sur le disque et envoie son contenu directement à l’écran. Si le JSON est écrit sur une seule ligne ou mal indenté, il s’affichera exactement de cette façon.

Ensuite, affichons exactement le même fichier en utilisant jq, sans appliquer de filtre particulier :

jq '.' user.json

Résultat affiché dans le terminal :

{
  "name": "Alice",
  "age": 30,
  "city": "Paris"
}

Cette simple commande montre déjà l’un des premiers intérêts de jq : reformater automatiquement un JSON brut pour le rendre lisible, avec une indentation claire et propre, directement depuis le terminal.

Accéder à une propriété simple

Pour accéder à une clé précise dans un objet JSON, jq utilise une syntaxe très intuitive basée sur le point.

Si votre JSON contient une clé name, vous pouvez demander à jq d’afficher uniquement cette valeur. jq parcourt l’objet et renvoie exactement ce que vous lui avez demandé.

jq '.name' user.json
## Affichera comme résultat : "Alice"

Ce principe fonctionne aussi avec des objets imbriqués. Si une clé se trouve à l’intérieur d’un autre objet, il suffit d’enchaîner les points pour descendre dans la structure.

Nouveau contenu du fichier user.json :

{
  "name": "Alice",
  "age": 30,
  "address": {
    "city": "Paris",
    "postal_code": "75000"
  }
}

Pour accéder à la ville, qui se trouve à l’intérieur de l’objet address, la commande jq consiste simplement à enchaîner les clés avec des points :

jq '.address.city' user.json

jq descend alors naturellement dans la structure JSON et renvoie uniquement la valeur correspondant à la clé demandée :

## "Paris"

Ce mécanisme est fondamental. Une fois compris, il ouvre la porte à quasiment toutes les manipulations possibles avec jq.

Travailler avec des tableaux JSON

Les tableaux sont extrêmement fréquents dans le JSON, notamment dans les réponses d’API. jq permet de les parcourir très simplement.

Lorsque vous appliquez un filtre à un tableau, jq peut soit renvoyer le tableau entier, soit traiter chaque élément individuellement. Pour cela, on utilise une notation qui indique à jq de parcourir chaque entrée.

Par exemple, si votre JSON contient une liste d’utilisateurs, jq peut afficher uniquement les noms de tous les utilisateurs, sans afficher le reste des données.

{
  "users": [
    {
      "name": "Alice",
      "age": 30,
      "city": "Paris"
    },
    {
      "name": "Bob",
      "age": 25,
      "city": "Lyon"
    },
    {
      "name": "Claire",
      "age": 35,
      "city": "Marseille"
    }
  ]
}

Pour parcourir le tableau et afficher uniquement le nom de chaque utilisateur, la commande jq s’écrit ainsi :

jq '.users[].name' users.json

Dans cette commande, la notation [] indique à jq de parcourir chaque élément du tableau users. jq applique ensuite le filtre .name à chaque entrée et renvoie uniquement la liste des noms, sans afficher les autres informations.

"Alice"
"Bob"
"Claire"

Ce fonctionnement peut surprendre au début, mais il devient très naturel avec un peu de pratique. jq agit comme un projecteur qui éclaire uniquement ce qui vous intéresse.

Filtrer des données selon un critère

C’est ici que jq commence vraiment à briller. Il est possible de filtrer des objets selon une condition précise.

Vous pouvez demander à jq de ne garder que les éléments dont une valeur correspond à un critère. Par exemple, afficher uniquement les utilisateurs majeurs, ou uniquement les produits dont le prix dépasse un certain montant.

jq '.users[] | select(.age >= 18)' users.json

Cette commande demande à jq de parcourir chaque utilisateur du tableau users, puis de ne conserver que ceux dont l’âge est supérieur ou égal à 18. jq applique la condition naturellement et renvoie uniquement les objets correspondant au critère défini. Cette commande renverra dont :

{
  "name": "Alice",
  "age": 30,
  "city": "Paris"
}
{
  "name": "Bob",
  "age": 25,
  "city": "Lyon"
}
{
  "name": "Claire",
  "age": 35,
  "city": "Marseille"
}

Les filtres de jq sont lisibles et proches du langage naturel. On exprime une condition, et jq fait le reste.

Cette capacité de filtrage est extrêmement utile dans le terminal, car elle permet de réduire instantanément un volume important de données à l’essentiel.

Utiliser jq avec des commandes du terminal

jq prend toute sa puissance lorsqu’il est combiné avec d’autres commandes. Il peut recevoir le résultat d’un curl, d’un cat, ou de n’importe quelle commande qui produit du JSON.

Par exemple, une requête HTTP vers une API peut être directement analysée sans jamais enregistrer le résultat dans un fichier. jq reçoit la réponse, filtre les données et affiche le résultat final.

curl https://api.example.com/users | jq '.users[].name'

Dans cette commande, curl effectue la requête HTTP et récupère une réponse JSON depuis l’API. Ce JSON est immédiatement transmis à jq, qui filtre les données pour n’afficher que le nom de chaque utilisateur, sans jamais enregistrer la réponse dans un fichier.

En savoir plus sur le symbole pipe |

Cette approche est idéale pour tester une API, déboguer une réponse ou automatiser des vérifications rapides.

Gérer les erreurs et les valeurs manquantes

Un JSON réel n’est pas toujours parfait. Certaines clés peuvent être absentes, certaines valeurs nulles. jq propose des mécanismes simples pour gérer ces situations sans provoquer d’erreur.

Il est possible de fournir des valeurs par défaut, d’ignorer certains éléments ou de vérifier l’existence d’une clé avant de l’utiliser. Ces précautions rendent vos commandes plus robustes et évitent des résultats inattendus.

Pour fournir une valeur par défaut lorsqu’une clé n’existe pas ou vaut null :

jq '.city // "Ville inconnue"' user.json

Si la clé city est absente ou à null, jq affichera automatiquement "Ville inconnue" au lieu de provoquer un résultat vide.

Pour vérifier l’existence d’une clé avant de l’utiliser :

jq 'select(has("city")) | .city' user.json

Cette commande demande à jq de ne traiter l’objet que s’il possède la clé city, ce qui évite toute tentative d’accès invalide.

Pour ignorer les valeurs nulles dans un tableau :

jq '.users[] | select(.email != null)' users.json

Ici, jq parcourt la liste des utilisateurs et conserve uniquement ceux dont la clé email contient une valeur exploitable. Ces mécanismes permettent d’écrire des commandes jq plus fiables, capables de gérer des JSON imparfaits rencontrés en conditions réelles.

C’est un point souvent négligé par les débutants, mais qui fait toute la différence dans un usage réel.

Premiers réflexes pour bien débuter avec jq

Lorsque vous débutez, prenez l’habitude d’afficher le JSON complet avant de le filtrer. Cela permet de bien comprendre sa structure. Ensuite, descendez progressivement dans les niveaux, clé par clé.

N’essayez pas de tout faire en une seule commande complexe. jq se maîtrise par petites étapes. Chaque filtre simple ajouté vous rapproche du résultat final.

Enfin, testez, expérimentez, cassez vos commandes. jq est un outil très permissif, et c’est en jouant avec que l’on progresse le plus vite.

Transformer des données JSON avec jq

Jusqu’ici, jq vous a surtout servi à lire et filtrer des données. Mais sa vraie force apparaît lorsqu’on commence à transformer le JSON. Et rassurez-vous, le mot peut sembler intimidant, mais les mécanismes restent simples.

Transformer, cela signifie modifier la forme des données pour les rendre plus utiles. Vous pouvez renommer des clés, supprimer des informations inutiles, regrouper plusieurs valeurs ou même créer un nouvel objet JSON à partir de données existantes.

Des formations informatique pour tous !

Débutant ou curieux ? Apprenez le développement web, le référencement, le webmarketing, la bureautique, à maîtriser vos appareils Apple et bien plus encore…

Formateur indépendant, professionnel du web depuis 2006, je vous accompagne pas à pas et en cours particulier, que vous soyez débutant ou que vous souhaitiez progresser. En visio, à votre rythme, et toujours avec pédagogie.

Découvrez mes formations Qui suis-je ?

Imaginons une réponse d’API qui retourne beaucoup trop d’informations alors que vous n’en avez besoin que de trois. jq vous permet de reconstruire un JSON propre, léger et parfaitement adapté à votre besoin.

Créer un nouvel objet JSON

Avec jq, vous pouvez créer un objet JSON “à la main” à partir de données existantes. Le principe est simple : vous définissez la structure de sortie et vous indiquez quelles valeurs y placer.

Prenons un JSON contenant un utilisateur avec de nombreuses informations. Vous souhaitez obtenir un objet plus lisible avec uniquement le nom complet et la ville. jq vous permet de créer un nouvel objet avec des clés personnalisées, même si elles n’existent pas dans le JSON d’origine.

Imaginons le fichier user.json suivant, contenant plusieurs informations :

{
  "first_name": "Alice",
  "last_name": "Dupont",
  "age": 30,
  "email": "alice.dupont@example.com",
  "address": {
    "city": "Paris",
    "postal_code": "75000"
  }
}

Commande jq permettant de créer un nouvel objet JSON personnalisé :

jq '{ full_name: (.first_name + " " + .last_name), city: .address.city }' user.json

Résultat affiché dans le terminal :

{
  "full_name": "Alice Dupont",
  "city": "Paris"
}

Dans cet exemple, jq ne se contente pas d’extraire des valeurs. Il reconstruit un nouvel objet JSON, avec des clés explicites et une structure plus lisible, sans jamais modifier le fichier d’origine.

Ce mécanisme est extrêmement pratique lorsque vous devez transmettre des données à un autre outil ou à un autre service. Vous adaptez le format sans jamais toucher au fichier source.

Modifier et renommer des clés

Il arrive souvent que les clés d’un JSON ne soient pas très explicites ou ne correspondent pas à ce que vous souhaitez afficher. jq permet de renommer des clés très facilement lors de la transformation.

Vous pouvez par exemple transformer une clé first_name et last_name en une seule clé full_name. Cette fusion de données est fluide et lisible avec jq, sans logique complexe.

Contenu du fichier user.json :

{
  "first_name": "Alice",
  "last_name": "Dupont",
  "age": 30
}

Commande jq permettant de fusionner et renommer les clés :

jq '{ full_name: (.first_name + " " + .last_name) }' user.json

Retour affiché par jq dans le terminal :

{
  "full_name": "Alice Dupont"
}

Dans cet exemple, jq crée une nouvelle clé full_name qui n’existait pas dans le JSON d’origine, en combinant les valeurs de first_name et last_name, le tout sans logique complexe ni modification du fichier source.

Ce genre de manipulation est très apprécié lorsqu’on prépare des données pour un affichage, un export CSV ou une consommation par un script plus simple.

Supprimer des données inutiles

Parfois, le problème n’est pas ce qu’il manque, mais ce qu’il y a en trop. jq permet de supprimer certaines clés d’un objet JSON sans difficulté.

Vous pouvez choisir d’ignorer une clé précise ou même de nettoyer complètement une structure en profondeur. Cela permet de rendre vos données plus claires et plus légères.

Contenu du fichier user.json :

{
  "name": "Alice",
  "age": 30,
  "email": "alice.dupont@example.com",
  "password": "secret123",
  "city": "Paris"
}

Commande jq pour supprimer une clé précise :

jq 'del(.password)' user.json

Retour affiché dans le terminal :

{
  "name": "Alice",
  "age": 30,
  "email": "alice.dupont@example.com",
  "city": "Paris"
}

Si vous souhaitez nettoyer davantage la structure, par exemple en supprimant plusieurs clés à la fois :

jq 'del(.password, .email)' user.json

Retour affiché :

{
  "name": "Alice",
  "age": 30,
  "city": "Paris"
}

Ces commandes permettent d’alléger un JSON en retirant les informations inutiles ou sensibles, tout en conservant une structure claire et exploitable.

Dans un contexte réel, c’est souvent utilisé pour retirer des métadonnées, des identifiants internes ou des informations sensibles avant un partage ou un envoi.

Effectuer des calculs avec jq

Oui, jq sait aussi faire des calculs. Et cela change beaucoup de choses.

Vous pouvez additionner des valeurs, calculer une moyenne, comparer des nombres ou même créer des champs calculés. Par exemple, transformer un prix hors taxe en prix TTC, ou additionner plusieurs montants contenus dans un tableau.

Ce type de calcul est très utile lorsque vous analysez des données financières, des statistiques ou des exports de bases de données. jq vous évite d’écrire un script complet juste pour obtenir un chiffre.

Imaginons le fichier product.json contenant un prix hors taxe :

{
  "name": "Agrafe inox",
  "price_ht": 100
}

Commande jq pour calculer un prix TTC avec une TVA à 20 % :

jq '{ name: .name, price_ttc: (.price_ht * 1.20) }' product.json

Retour affiché dans le terminal :

{
  "name": "Agrafe inox",
  "price_ttc": 120
}

Autre cas fréquent : additionner des montants contenus dans un tableau.
Imaginons le fichier orders.json :

{
  "amounts": [120, 80, 50]
}

Commande jq pour calculer le total :

jq '.amounts | add' orders.json

Retour affiché :

250

Ces exemples montrent comment jq permet de réaliser rapidement des calculs utiles directement depuis le terminal, sans écrire le moindre script dédié.

Là encore, la syntaxe reste lisible, ce qui permet de comprendre ce que fait la commande même plusieurs semaines plus tard.

Trier et ordonner des données

Quand on travaille avec des tableaux JSON, l’ordre des éléments a parfois son importance. jq permet de trier des données selon une clé précise.

Vous pouvez trier une liste d’objets par ordre alphabétique, par date ou par valeur numérique. Ce tri peut être croissant ou décroissant selon vos besoins.

Imaginons le fichier users.json contenant une liste d’utilisateurs :

{
  "users": [
    { "name": "Claire", "age": 35 },
    { "name": "Alice", "age": 30 },
    { "name": "Bob", "age": 25 }
  ]
}

Commande jq pour trier les utilisateurs par âge, par ordre croissant :

jq '.users | sort_by(.age)' users.json

Retour affiché dans le terminal :

[
  { "name": "Bob", "age": 25 },
  { "name": "Alice", "age": 30 },
  { "name": "Claire", "age": 35 }
]

Pour effectuer un tri décroissant, il suffit d’inverser le résultat :

jq '.users | sort_by(.age) | reverse' users.json

Retour affiché :

[
  { "name": "Claire", "age": 35 },
  { "name": "Alice", "age": 30 },
  { "name": "Bob", "age": 25 }
]

Ces commandes montrent comment jq permet d’ordonner facilement des données selon différents critères, directement depuis le terminal.

C’est un usage très courant lorsqu’on analyse des résultats ou qu’on souhaite afficher les éléments les plus importants en premier.

Convertir du JSON vers du texte exploitable

Par défaut, jq renvoie du JSON. Mais il peut aussi produire du texte simple, parfaitement exploitable par d’autres commandes du terminal.

Vous pouvez par exemple afficher uniquement une liste de valeurs, sans guillemets ni structure JSON. Cela permet de chaîner jq avec des outils comme grep, sort, uniq ou même de rediriger le résultat vers un fichier texte.

maginons le fichier users.json suivant :

{
  "users": [
    { "name": "Alice" },
    { "name": "Bob" },
    { "name": "Alice" }
  ]
}

Commande jq pour afficher uniquement les valeurs, sans structure JSON ni guillemets :

jq -r '.users[].name' users.json

Retour affiché dans le terminal :

Alice
Bob
Alice

Ce format texte est directement exploitable par d’autres commandes du terminal. Par exemple, pour trier les noms et supprimer les doublons :

jq -r '.users[].name' users.json | sort | uniq

Retour obtenu :

Alice
Bob

Grâce à l’option -r, jq devient un outil parfaitement compatible avec les chaînes de commandes du terminal et les traitements automatisés.

Ce mode de fonctionnement est souvent utilisé dans les scripts shell pour automatiser des tâches. jq devient alors une brique essentielle dans un pipeline.

Utiliser jq dans des scripts automatisés

Une fois que vous êtes à l’aise avec jq, il devient naturel de l’intégrer dans des scripts. Que ce soit pour vérifier une réponse d’API, analyser un fichier de configuration ou surveiller un service, jq permet de prendre des décisions basées sur des données JSON.

Vous pouvez par exemple tester si une valeur existe, comparer un résultat attendu ou déclencher une action selon le contenu du JSON.

Cette capacité d’analyse conditionnelle est l’une des raisons pour lesquelles jq est autant utilisé dans les environnements professionnels.

Tableau récapitulatif des commandes et paramètres essentiels de jq

Pour conclure la partie technique, voici un tableau récapitulatif des usages les plus courants de jq. Ce tableau peut servir de pense-bête au quotidien.

Ce tableau couvre déjà une très large majorité des besoins courants, surtout lorsqu’on débute.

Apprendre à utiliser jq, c’est un peu comme découvrir un super pouvoir discret. Au début, on s’en sert simplement pour lire un fichier plus proprement. Puis, très vite, on se surprend à filtrer, transformer et analyser des données en quelques secondes depuis le terminal.

jq ne remplace pas un langage de programmation, mais il comble un vide énorme entre le JSON brut et son exploitation concrète. Il fait gagner du temps, réduit la complexité et apporte une vraie satisfaction quand une commande bien pensée donne exactement le résultat attendu.

Si vous travaillez régulièrement avec des APIs, des fichiers de configuration ou des exports de données, jq mérite clairement une place permanente dans votre environnement. Prenez le temps de pratiquer, d’expérimenter et de jouer avec. C’est souvent dans ces moments-là que l’on comprend vraiment la puissance du terminal… et qu’on commence à l’aimer un peu plus.

Alban

Fondateur de l’agence Créa-troyes, affiliée France Num
Intervenant en Freelance.
Contactez-moi

crea-troyes.fr