JMESPath (pronounced 'james path') is a query language for JSON that allows you to declaratively extract, filter, and transform elements from JSON documents or Python dictionaries. Current stable version is 1.0.0 (1.1.0 on PyPI as of 2026). The project is mature and low-churn — it reached 1.0 in 2022 with no breaking API changes, and releases are infrequent. It is a foundational dependency of boto3/botocore and is used by the AWS CLI --query flag.
Install & Compatibility
Where this runs
tested against v1.1.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.043s · 17.9MB
glibcpy 3.10–3.925 runs
installs and imports cleanly · install 1.5s · import 0.040s · 18MB
16MB installed
● package 16MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
jmespath
✓ import jmespath
Top-level module; jmespath.search() and jmespath.compile() are the primary entry points.
functions.Functions
✓ from jmespath import functions
Required base class for custom function extensions; subclass functions.Functions and prefix methods with _func_.
functions.signature
✓ from jmespath.functions import signature
Decorator used to declare argument types for custom jmespath functions.
Options
✓ jmespath.Options(dict_cls=..., custom_functions=...)
Pass an Options instance as the third argument to search() or compiled_expr.search() to control dict ordering or inject custom functions.
One-shot search, compiled reuse, filter projection, and custom Options.
import jmespath
from jmespath import functions
# 1. One-shot search
data = {
"people": [
{"name": "Alice", "age": 30},
{"name": "Bob", "age": 17},
{"name": "Carol", "age": 25},
]
}
# Returns all names
names = jmespath.search("people[*].name", data)
print(names) # ['Alice', 'Bob', 'Carol']
# Filter: only adults
adults = jmespath.search("people[?age >= `18`].name", data)
print(adults) # ['Alice', 'Carol']
# 2. Compile once, search many times (avoids re-parsing)
expr = jmespath.compile("people[*].age")
print(expr.search(data)) # [30, 17, 25]
# 3. Pipe to index into a projection result (not people[*].name[0]!)
first_name = jmespath.search("people[*].name | [0]", data)
print(first_name) # 'Alice'
# 4. Custom function via Options
class MyFunctions(functions.Functions):
@functions.signature({"types": ["string"]})
def _func_upper(self, s):
return s.upper()
opts = jmespath.Options(custom_functions=MyFunctions())
result = jmespath.search("people[0].name | upper(@)", data, opts)
print(result) # 'ALICE'
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'jmespath'
The 'jmespath' package is not installed or not accessible in the current Python environment. This often occurs if it was not installed, or installed in a different Python interpreter/virtual environment than the one being used.
fixRun `pip install jmespath` to install the library.
AttributeError: module 'jmespath' has no attribute 'search'
This error typically occurs when a local Python file named `jmespath.py` exists in the same directory or an earlier directory in the Python path, shadowing the installed `jmespath` library.
fixRename the conflicting local `jmespath.py` file to something else to avoid the name collision, or ensure the correct `jmespath` library is being imported.
jmespath.exceptions.ParseError: Expecting: ..., got: ...
The JMESPath expression provided contains a syntax error, such as incorrect quoting, missing operators, or malformed function calls. The '...' in the error message indicates what was expected versus what was found.
fixReview and correct the JMESPath expression syntax, paying close attention to proper quoting (e.g., single quotes for string literals, backticks for numbers/booleans in some contexts, double quotes for identifiers with special characters), correct use of operators, and valid function argument structures.
TypeError: <function_name>() expected argument 1 to be type <expected_type> but received type <received_type> instead
A JMESPath function was invoked with an argument of an incorrect data type, which does not match the function's expected signature. JMESPath functions have strict type requirements for their arguments.
fixEnsure that the arguments passed to JMESPath functions are of the correct type as specified in the function's documentation. Use type conversion functions like `to_string()`, `to_number()`, etc., within the JMESPath expression if necessary to match the expected argument types.
Audit
Dependencies
No dependency data recorded yet.