The ProblemYou’ve spent thirty minutes crafting the perfect JMESPath query to parse a 500-line JSON response from a cloud API. You run your playbook, but instead of the expected data, the task fails instantly with a frustrating dependency error:
The task includes an option with an undefined variable. The error was: 'json_query' filter requires 'jmespath' to be installed on the Ansible controller
This error typically strikes right after setting up a new control node or migrating to a fresh CI/CD runner. While the message is clear about what is missing, the solution depends on how you manage your Python environment.
Why This HappensAnsible keeps its core installation lean by not bundling every possible library. The json_query filter is actually a wrapper for JMESPath, a powerful query language for JSON. Because Ansible is a Python application, it needs this library installed in the same Python environment that is currently running your Ansible core code.
Crucially, this library must reside on your Ansible Controller—the machine where you trigger the ansible-playbook command. You do not need to install it on your remote managed servers. If you use a tool like GitHub Actions, the dependency must be part of that runner's environment.
Step-by-Step Fix### Method 1: Install via Pip (Standard)If you installed Ansible using pip, this is usually the quickest fix. First, verify which Python version your Ansible installation is currently using:
ansible --version | grep "python version"
Once you have the version, install the library. For a standard Python 3 setup, use:
pip3 install jmespath
If you are managing multiple Python versions, you might need to use python3 -m pip install jmespath to ensure it hits the correct site-packages directory.
Method 2: Working with Virtual EnvironmentsProfessional workflows often use virtual environments (venvs) to prevent package conflicts. A global installation won't help if Ansible is running inside a silo. Activate your project's environment first:
source /opt/ansible-venv/bin/activate
pip install jmespath
If you aren't sure where your Ansible binary lives, run which ansible. If the path points to a folder inside your project directory, you are almost certainly using a virtual environment.
Method 3: System Package ManagersLinux administrators often prefer using apt or dnf to keep dependencies stable across the entire operating system.
For Ubuntu or Debian:
sudo apt update
sudo apt install python3-jmespath
For RHEL, CentOS, or Fedora:
sudo dnf install python3-jmespath
Verification: A Quick Sanity CheckDon't wait for a 10-minute playbook run to see if the fix worked. Use this one-line ad-hoc command to test the filter against your local machine:
ansible localhost -m debug -a "msg={{ {'status': 'active'} | json_query('status') }}"
Expected Output:
localhost | SUCCESS => {
"msg": "active"
}
If you see "msg": "active", the dependency is correctly mapped. If the error persists, check if you accidentally installed jmespath for Python 2.7 while Ansible is running on 3.10+.
Pro-Tips for JSON FilteringDebugging complex queries inside a playbook is slow. If your query returns the wrong data, Ansible often throws a generic "undefined variable" error that hides the real syntax problem.
Before committing logic to a task, I use the JSON Formatter & Validator at ToolCraft to visualize the structure. I’ve wasted hours on filters only to realize the API returned a nested list instead of a flat object. Using a local or browser-based tool is much faster than running a playbook twenty times to find a missing dot in a query. If you are converting legacy config files, the YAML to JSON Converter can help you see exactly how your variables will look to the JMESPath engine.