JSONPath for Python

0.82.2 · active · verified Sat Apr 11

The `jsonpath` library provides a Pythonic implementation of JSONPath, following the IETF JSONPath draft specification. It allows users to query JSON-like data structures using XPath-like expressions. It's actively developed, with the latest version being 0.82.2, and typically releases updates as the IETF draft progresses or new features are added.

Warnings

breaking This library strictly adheres to the IETF JSONPath draft. Its syntax and behavior may differ significantly from other popular Python JSONPath implementations (e.g., `jsonpath_rw`, `jsonpath-ng`). Users migrating or expecting behavior from non-standard JSONPath libraries should carefully review the IETF specification and library documentation.
Fix: Consult the official documentation for the `jsonpath` library and the IETF JSONPath draft. Thoroughly test existing JSONPath expressions when migrating from other libraries.
gotcha For repeated queries with the same JSONPath expression, using `jsonpath.select()` repeatedly is less efficient than instantiating a `JSONPath` object once and calling its `findall()` method. `select()` re-compiles the path on each call.
Fix: For performance-sensitive applications, instantiate `json_path = JSONPath("your_path")` once, and then call `json_path.findall(data)` or `json_path.find(data)` for each query.
gotcha The `JSONPath` object has both `find()` and `findall()` methods. `find()` returns the first matching element (or `None`), while `findall()` returns a list of all matching elements. Confusing these can lead to unexpected results (e.g., only getting one match when multiple exist).
Fix: Always use `findall()` when you expect or need all potential matches from a JSONPath expression. Use `find()` only when you explicitly need the first result or know there's at most one.

Install

pip install jsonpath Install stable version

Imports

jsonpath
```
import jsonpath
```
Import the module to access `jsonpath.select` for convenience or `jsonpath.JSONPath` for object-oriented usage.
JSONPath
```
from jsonpath import JSONPath
```
Import the main class to compile and reuse JSONPath expressions.
select
```
from jsonpath import select
```
Import the convenience function to directly query data without explicit class instantiation.

Quickstart

This quickstart demonstrates how to use the `jsonpath.select` convenience function for simple queries, and how to use the `jsonpath.JSONPath` class for compiling and reusing path expressions, which is more efficient for repeated queries against different data.

import jsonpath

data = {
    "store": {
        "book": [
            {"category": "reference", "author": "Nigel Rees", "title": "Sayings of the Century", "price": 8.95},
            {"category": "fiction", "author": "Evelyn Waugh", "title": "Sword of Honour", "price": 12.99}
        ],
        "bicycle": {"color": "red", "price": 19.95}
    }
}

# Use the convenience 'select' function to query data
path_expression = "$.store.book[*].author"
authors = jsonpath.select(path_expression, data)
print(f"Authors found: {authors}")

# For performance-critical scenarios, compile the path once using JSONPath class
from jsonpath import JSONPath
json_path = JSONPath(path_expression)
authors_compiled = json_path.findall(data)
print(f"Authors (compiled path): {authors_compiled}")

view raw JSON →