jsonpath-ng is a robust and significantly extended implementation of JSONPath for Python. It aims to be standard compliant, including arithmetic and binary comparison operators, and provides a clear Abstract Syntax Tree (AST) for metaprogramming. As of version 1.8.0, it is actively maintained with a regular release cadence, merging functionalities from older libraries like jsonpath-rw and jsonpath-rw-ext.
Install & Compatibility
Where this runs
tested against v1.8.0 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.925 runs
installs and imports cleanly · install 0.0s · import 0.067s · 18.3MB
glibcpy 3.10–3.925 runs
installs and imports cleanly · install 1.6s · import 0.057s · 19MB
16MB installed
● package 16MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
parse
✓ from jsonpath_ng import parse
✗ from jsonpath_ng.ext import parse
The core `parse` function for standard JSONPath is directly available from `jsonpath_ng`. Use `jsonpath_ng.ext.parse` only for extended features if explicitly needed.
jsonpath
✓ from jsonpath_ng import jsonpath
Provides programmatic construction of JSONPath expressions without string parsing, though `parse` is more commonly used for string expressions.
This quickstart demonstrates how to parse JSON data, extract specific elements using JSONPath expressions, filter results, and update values within a JSON structure. It covers the core `parse` and `find` methods, as well as a basic `update` operation.
from jsonpath_ng import jsonpath, parse
import json
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},
{"category": "fiction", "author": "Herman Melville", "title": "Moby Dick", "isbn": "0-553-21311-3", "price": 8.99},
{"category": "fiction", "author": "J.R.R. Tolkien", "title": "The Lord of the Rings", "isbn": "0-395-19395-8", "price": 22.99}
],
"bicycle": {"color": "red", "price": 19.95}
},
"expensive": 10
}
# Find all book titles
jsonpath_expr = parse('$.store.book[*].title')
matches = jsonpath_expr.find(data)
book_titles = [match.value for match in matches]
print(f"Book Titles: {book_titles}")
# Find books cheaper than $10
jsonpath_expr = parse('$.store.book[?(@.price < 10)].title')
matches = jsonpath_expr.find(data)
cheap_books = [match.value for match in matches]
print(f"Cheap Books (titles): {cheap_books}")
# Update a value (e.g., change bicycle color)
update_expr = parse('$.store.bicycle.color')
updated_data = update_expr.update(data, 'blue')
print(f"Updated Bicycle Color: {updated_data['store']['bicycle']['color']}")
Debug
Known issues
breakingPython 3.7 support was removed in v1.7.0. Python 3.8 and 3.9 support were removed in v1.8.0. Users on these Python versions must upgrade to Python 3.10 or newer to use jsonpath-ng >= 1.8.0.fixUpgrade your Python environment to 3.10 or newer.
affects: >=1.7.0 (for 3.7), >=1.8.0 (for 3.8, 3.9)
gotchaThe `find()` method returns a list of `DatumInContext` objects, even if only one or no matches are found. Users commonly forget to check if the list is empty before accessing `[0].value`, leading to an `IndexError`.fixAlways check if the `matches` list is not empty (e.g., `if matches: value = matches[0].value`) or use a list comprehension if expecting multiple results.
affects: All versions
gotchaIn older versions, updating a JSON object using `jsonpath_expr.update()` could fail with `TypeError` if the target value was `None` or a boolean. While fixes have been implemented (e.g., for boolean values in v1.7.0, and null values in earlier patches), ensure you are on a recent version if experiencing such issues.fixUpgrade to the latest version of `jsonpath-ng` to benefit from these fixes, especially if performing `update` operations on data that might contain `None` or boolean values.
affects: <1.7.0 (for boolean), pre-v1.0.0 (for null)
gotchaThe library internally uses `this` to refer to the 'current object' within a filter expression, rather than the `@` symbol often seen in other JSONPath implementations. While `@` might work in simple cases due to parsing ambiguities, `this` is the explicit and recommended syntax for clarity and correctness.fixUse `this` (e.g., `[?(this.price < 10)]`) instead of `@` when referencing the current object within filter expressions.
affects: All versions
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'jsonpath_ng'
The `jsonpath-ng` library is not installed or is not accessible in the current Python environment.
fixEnsure the library is installed using pip: `pip install jsonpath-ng`
jsonpath_ng.exceptions.JsonPathLexerError: Error on line 1, col X: Unexpected character: ?
This error often occurs when using filter expressions `[?()]` with the default `jsonpath_ng.parse` function, which might not fully support advanced filter syntax from other JSONPath implementations.
fixFor extended filter syntax and other advanced features, import `parse` from `jsonpath_ng.ext` instead: `from jsonpath_ng.ext import parse`
jsonpath_ng.exceptions.JsonPathParserError: Parse error at X:Y near token Z (NUMBER)
This error typically occurs when attempting to access a dictionary key that is a string containing only digits using dot notation (e.g., `$.data.1`), as `jsonpath-ng` interprets it as a numerical index.
fixAccess string keys that look like numbers using bracket notation with quotes: `jsonpath_expr = parse('$.data["1"]')` AttributeError: 'DatumInContext' object has no attribute 'key'
The `DatumInContext` object returned by `find()` in `jsonpath-ng` does not have a direct `key` attribute to retrieve the key of the matched element; it primarily provides `value`, `path`, and `context`.
fixTo get the key, you need to access it from the `path` attribute of the `DatumInContext` object, typically by checking if the path is a `Child` or `Fields` instance and extracting its `field_name`: `[match.path.field_name for match in jsonpath_expr.find(data) if isinstance(match.path, (jsonpath_ng.jsonpath.Child, jsonpath_ng.jsonpath.Fields))]`
Audit
Dependencies
No dependency data recorded yet.