The support matrix, and which Python is which · Ansible

Ansible has two Python requirements, and almost every question about version compatibility becomes easy the moment you stop treating them as one.

The controller runs ansible-playbook. It needs a Python that the installed ansible-core supports, and that requirement is strict — pip will refuse the install outright if it is not met.

The managed node executes the module payload the controller ships it. It needs a Python in a much wider, much older range, because a fleet contains machines built over a decade.

These are different numbers. They move on different schedules. They fail in different ways.

The matrix

For ansible-core releases around the one this course targets:

`ansible-core`	Controller Python	Managed-node Python
2.21	3.12 – 3.14	3.9 – 3.14
2.20	3.12 – 3.14	3.9 – 3.14
2.19	3.11 – 3.13	3.8 – 3.13
2.18	3.11 – 3.13	3.8 – 3.13

Read it as two independent questions:

Will ansible-core 2.21 install and run on this controller? Look at column two.
Can a controller running 2.21 manage this host? Look at column three, against whatever Python the host has.

The controller requirement is not a recommendation. It is encoded in the package metadata, and pip enforces it:

Read-only / Safethe requirement, straight from the installed package— Reads the metadata of the installed ansible-core rather than the documentation. This is the number pip actually checks, so it is the number that decides whether an install succeeds.

$ python -c "import importlib.metadata as m; d = m.metadata('ansible-core'); print(d['Version'], d['Requires-Python'])"

2.21.3 >=3.12

The upper bound is not expressed as a metadata constraint — it is the range upstream tests and supports, published in the matrix and reflected in the package classifiers:

Read-only / Safethe tested interpreters— The Programming Language classifiers name the Python versions upstream builds and tests against. A newer interpreter may work; it is not supported.

$ python -c "import importlib.metadata as m; [print(c) for c in m.metadata('ansible-core').get_all('Classifier') if 'Python :: 3.' in c]"

Programming Language :: Python :: 3.12
Programming Language :: Python :: 3.13
Programming Language :: Python :: 3.14

Why distribution packages lag

An estate that installs Ansible with apt install ansible gets whatever its release froze. That is the whole design of a stable distribution and it is not a defect — but it means the version you get is a property of your operating system release date, not of what Ansible currently ships.

Read-only / Safewhat the distribution actually offers— Shows the installed and candidate versions from the configured repositories. Read the candidate line: that is the newest version this system can install without adding a third-party source.

$ apt-cache policy ansible ansible-core

ansible:
Installed: 13.1.0+dfsg-1ubuntu1
Candidate: 13.1.0+dfsg-1ubuntu1
Version table:
*** 13.1.0+dfsg-1ubuntu1 500
      500 http://archive.example.com/ubuntu resolute/universe amd64 Packages
      100 /var/lib/dpkg/status
ansible-core:
Installed: 2.20.1-1
Candidate: 2.20.1-1
Version table:
*** 2.20.1-1 500
      500 http://archive.example.com/ubuntu resolute/universe amd64 Packages
      100 /var/lib/dpkg/status

That is a real distribution offering community package 13.1.0, which is ansible-core 2.20.1 — one minor release behind the 2.21.x this course targets. There is nothing wrong with 2.20. But if your repository declares 2.21 and your controller is a distribution package, the declaration is fiction, and every claim you have verified was verified against something else.

The gap grows with the age of the distribution release. On a long-term-support base two years into its life, the packaged ansible-core can be three or four minor releases behind, with deprecations already removed upstream that your playbooks still rely on — or, more awkwardly, deprecation warnings you have never seen because your version does not emit them yet.

Answering the real question from the table

The question that comes up in practice is not “which Python do I have”. It is “can this controller manage that host” — usually asked about the oldest machine in the estate, ten minutes before a change window.

Work it in two steps.

Step one: what does the controller run?

Read-only / Safecontroller side— The python version line is the interpreter running ansible-core, not necessarily the system default. On a virtualenv controller these differ, which is the point of the virtualenv.

$ ansible --version

ansible [core 2.21.3]
config file = /home/ops/estate/ansible.cfg
configured module search path = ['/home/ops/.ansible/plugins/modules']
ansible python module location = /home/ops/.venvs/estate/lib/python3.12/site-packages/ansible
executable location = /home/ops/.venvs/estate/bin/ansible
python version = 3.12.7
jinja version = 3.1.6

Illustrative output

Core 2.21, controller Python 3.12. Row one of the matrix, and it is within 3.12 – 3.14. The controller is fine.

Step two: what does the managed node run? Ask the host, not the matrix. If you can already reach it with Ansible, the fact is gathered for you; if you cannot, ssh and python3 --version answers it.

The matrix then says: 3.9 through 3.14 is supported by core 2.21. A RHEL 9 host with the platform Python 3.9 is inside the range. A long-abandoned box with Python 3.6 is not, and no amount of controller upgrading will change that — upgrading the controller moves the managed-node floor up, not down.

The failure that gets misdiagnosed

A run against ninety hosts succeeds on eighty-nine and fails on one, with a Python traceback in the module output rather than a clean Ansible error message.

The instinct is to suspect the controller — it is the machine that changed, it is the machine you can log into, and the error mentions Python. That instinct is wrong here, and following it costs an hour.

The controller’s Python is a single fact shared by all ninety hosts. If it were the problem, all ninety would have failed. A failure on one host in an otherwise healthy run is a property of that host, and on a mixed-age fleet the property is very often its interpreter: an old platform Python below the supported floor, or a host where python3 resolves to something surprising.

The diagnosis is a single fact gathered from the failing host:

Read-only / Safewhat interpreter did Ansible actually choose there?— Gathers facts from one host and prints the interpreter Ansible discovered. Fact gathering connects and runs a module, so this is read-only but not free - it opens an SSH session.

$ ansible db07.example.com -m setup -a 'filter=ansible_python' | head -20

db07.example.com | SUCCESS => {
  "ansible_facts": {
      "ansible_python": {
          "executable": "/usr/bin/python3.8",
          "has_sslcontext": true,
          "type": "cpython",
          "version": {
              "major": 3,
              "minor": 8,
              "micro": 18,
              "releaselevel": "final",
              "serial": 0
          },
          "version_info": [3, 8, 18, "final", 0]
      }
  },
  "changed": false
}

Illustrative output

Python 3.8, against a core 2.21 floor of 3.9. The host is below the matrix. The controller is innocent, the playbook is innocent, and the fix is on the managed node — which is a different team’s ticket and a different change window, so knowing this in ten minutes rather than two hours matters.

Under the hood

Nothing about the controller’s Python is installed on the managed node. The controller builds a payload — the module source plus its module_utils dependencies — and ships it; the managed node executes it with its own interpreter. That is why the two requirements are genuinely independent rather than merely documented separately.

It also explains the direction of the constraint. The module source has to be syntactically valid and semantically correct under the managed node’s interpreter, so the floor is set by what upstream is willing to keep the module code compatible with. When they stop supporting Python 3.8 on targets, it is because they have started writing module code that 3.8 cannot parse — which is why the failure surfaces as a traceback from inside the payload rather than as a version check.

Interpreter discovery — how ansible_python_interpreter gets its value, what auto does, and how to pin it per host — is a subject of its own and is covered later in the course. What you need here is only the separation: two Pythons, two ranges, two failure modes.

What happens if pip refuses to install ansible-core?

You will see a message naming the requirement rather than a traceback: ansible-core declares Requires-Python: >=3.12, and pip will not install a distribution whose requirement the current interpreter does not satisfy.

That is a good failure. It happens at install time, on one machine, with a clear message, before anything reaches the fleet.

The bad version of this problem is the one you create by working around it — installing an older ansible-core that does support your controller’s Python, without noticing that you have also moved the managed-node floor and the deprecation window. The right fix is a newer Python on the controller, which a virtualenv or pipx makes cheap and the next lesson covers.

On a modern distribution you may also meet PEP 668: the system Python is marked externally managed and pip refuses to install into it at all, regardless of version. That is not a version problem and --break-system-packages is not the answer. It is the distribution telling you to use an isolated environment, which is what you wanted anyway.

The matrix

Why distribution packages lag

Answering the real question from the table

The failure that gets misdiagnosed

Knowledge check