{"id":277,"library":"jmespath","title":"JMESPath","description":"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.","status":"active","version":"1.1.0","language":"python","source_language":"en","source_url":"https://github.com/jmespath/jmespath.py","tags":["json","query","data-extraction","aws","boto3","filtering","parsing"],"install":[{"cmd":"pip install jmespath","lang":"bash","label":"pip"}],"dependencies":[],"imports":[{"note":"Top-level module; jmespath.search() and jmespath.compile() are the primary entry points.","symbol":"jmespath","correct":"import jmespath"},{"note":"Required base class for custom function extensions; subclass functions.Functions and prefix methods with _func_.","symbol":"functions.Functions","correct":"from jmespath import functions"},{"note":"Decorator used to declare argument types for custom jmespath functions.","symbol":"functions.signature","correct":"from jmespath.functions import signature"},{"note":"Pass an Options instance as the third argument to search() or compiled_expr.search() to control dict ordering or inject custom functions.","symbol":"Options","correct":"jmespath.Options(dict_cls=..., custom_functions=...)"}],"quickstart":{"code":"import jmespath\nfrom jmespath import functions\n\n# 1. One-shot search\ndata = {\n    \"people\": [\n        {\"name\": \"Alice\", \"age\": 30},\n        {\"name\": \"Bob\",   \"age\": 17},\n        {\"name\": \"Carol\", \"age\": 25},\n    ]\n}\n\n# Returns all names\nnames = jmespath.search(\"people[*].name\", data)\nprint(names)  # ['Alice', 'Bob', 'Carol']\n\n# Filter: only adults\nadults = jmespath.search(\"people[?age >= `18`].name\", data)\nprint(adults)  # ['Alice', 'Carol']\n\n# 2. Compile once, search many times (avoids re-parsing)\nexpr = jmespath.compile(\"people[*].age\")\nprint(expr.search(data))  # [30, 17, 25]\n\n# 3. Pipe to index into a projection result (not people[*].name[0]!)\nfirst_name = jmespath.search(\"people[*].name | [0]\", data)\nprint(first_name)  # 'Alice'\n\n# 4. Custom function via Options\nclass MyFunctions(functions.Functions):\n    @functions.signature({\"types\": [\"string\"]})\n    def _func_upper(self, s):\n        return s.upper()\n\nopts = jmespath.Options(custom_functions=MyFunctions())\nresult = jmespath.search(\"people[0].name | upper(@)\", data, opts)\nprint(result)  # 'ALICE'\n","lang":"python","description":"One-shot search, compiled reuse, filter projection, and custom Options."},"warnings":[{"fix":"Parse first: jmespath.search(expr, json.loads(raw_string)) or response.json().","message":"jmespath.search() requires a parsed Python dict/list, NOT a raw JSON string. Passing a JSON string silently returns None or wrong results.","severity":"breaking","affected_versions":"all"},{"fix":"Upgrade to Python >=3.9 and pin jmespath>=1.0.0.","message":"Python 2 and Python <3.7 support was dropped in 1.0.0. The PyPI package requires Python >=3.9 as of 1.1.0.","severity":"breaking","affected_versions":"<1.0.0"},{"fix":"Use a pipe to stop the projection first: people[*].name | [0]","message":"Indexing into a wildcard projection (e.g. people[*].name[0]) does NOT return the first element of the projected list — it attempts to index each string, returning [].","severity":"gotcha","affected_versions":"all"},{"fix":"Use [*] to project over a list without flattening; use [] only when you explicitly need one-level flattening.","message":"[] (flatten) and [*] (wildcard) are NOT equivalent. [] flattens one level of nested arrays; [*] keeps the original list structure intact.","severity":"gotcha","affected_versions":"all"},{"fix":"Pin your jmespath version if you rely on custom functions, and audit after any upgrade.","message":"Custom function support is explicitly marked experimental by the authors; the API (signature decorator, _func_ naming) may change without a major version bump.","severity":"deprecated","affected_versions":"all"},{"fix":"Use jmespath.compile(expr) once and call compiled_expr.search(data) in the loop.","message":"Calling jmespath.search() with the same expression string in a hot loop re-parses the expression on every call, causing significant overhead.","severity":"gotcha","affected_versions":"all"},{"fix":"Always use backtick-delimited literals for numbers and booleans in filter expressions: [?count > `0`].","message":"Numeric literals in filter expressions must be wrapped in backticks, not quotes. people[?age > '18'] compares against a string; people[?age > `18`] compares against a number.","severity":"gotcha","affected_versions":"all"}],"env_vars":null,"last_verified":"2026-05-12T12:45:38.020Z","next_check":"2026-06-26T00:00:00.000Z","problems":[{"fix":"Run `pip install jmespath` to install the library.","cause":"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.","error":"ModuleNotFoundError: No module named 'jmespath'"},{"fix":"Rename the conflicting local `jmespath.py` file to something else to avoid the name collision, or ensure the correct `jmespath` library is being imported.","cause":"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.","error":"AttributeError: module 'jmespath' has no attribute 'search'"},{"fix":"Review 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.","cause":"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.","error":"jmespath.exceptions.ParseError: Expecting: ..., got: ..."},{"fix":"Ensure 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.","cause":"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.","error":"TypeError: <function_name>() expected argument 1 to be type <expected_type> but received type <received_type> instead"}],"ecosystem":"pypi","meta_description":null,"install_score":100,"install_tag":"verified","quickstart_score":80,"quickstart_tag":"verified","pypi_latest":null,"install_checks":{"last_tested":"2026-05-12","tag":"verified","tag_description":"installs cleanly on critical runtimes, fast import, recently tested","results":[{"runtime":"python:3.10-alpine","python_version":"3.10","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.04,"mem_mb":1.4,"disk_size":"17.9M"},{"runtime":"python:3.10-slim","python_version":"3.10","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.02,"mem_mb":1.4,"disk_size":"18M"},{"runtime":"python:3.11-alpine","python_version":"3.11","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.05,"mem_mb":1.5,"disk_size":"19.8M"},{"runtime":"python:3.11-slim","python_version":"3.11","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.04,"mem_mb":1.5,"disk_size":"20M"},{"runtime":"python:3.12-alpine","python_version":"3.12","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.05,"mem_mb":1.4,"disk_size":"11.7M"},{"runtime":"python:3.12-slim","python_version":"3.12","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.06,"mem_mb":1.4,"disk_size":"12M"},{"runtime":"python:3.13-alpine","python_version":"3.13","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.06,"mem_mb":1.8,"disk_size":"11.3M"},{"runtime":"python:3.13-slim","python_version":"3.13","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.06,"mem_mb":1.6,"disk_size":"12M"},{"runtime":"python:3.9-alpine","python_version":"3.9","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.03,"mem_mb":1.4,"disk_size":"17.4M"},{"runtime":"python:3.9-slim","python_version":"3.9","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.03,"mem_mb":1.4,"disk_size":"18M"}]},"quickstart_checks":{"last_tested":"2026-04-23","tag":"verified","tag_description":"quickstart runs on critical runtimes, recently tested","results":[{"runtime":"python:3.10-alpine","exit_code":0},{"runtime":"python:3.10-slim","exit_code":0},{"runtime":"python:3.11-alpine","exit_code":0},{"runtime":"python:3.11-slim","exit_code":0},{"runtime":"python:3.12-alpine","exit_code":0},{"runtime":"python:3.12-slim","exit_code":0},{"runtime":"python:3.13-alpine","exit_code":0},{"runtime":"python:3.13-slim","exit_code":0},{"runtime":"python:3.9-alpine","exit_code":0},{"runtime":"python:3.9-slim","exit_code":0}]}}