Installing: pipx, virtualenv, pip and the distro package · Ansible

There are four ways to put Ansible on a machine, and the tutorials that list them usually rank them by convenience. Convenience is the wrong axis. What decides whether an install is a problem in eighteen months is:

Which Python does it bind to — and can that Python change under you?
Can it be upgraded without touching the system — or does an Ansible upgrade become an operating-system event?
Can two versions coexist — because upgrading safely means running both for a while.
Is the result reproducible on another machine — from a file in the repository, not from memory.

The four paths

	Distro package	System-wide `pip`	`pipx`	Explicit venv
Binds to	System Python	System Python	An interpreter pipx picks, isolated	The interpreter you name
Version you get	Whatever the release froze	Newest that installs	Any, you choose	Any, you pin
Upgrade touches the system	Yes	Yes	No	No
Two versions coexist	No	No	With `--suffix`	Yes, trivially
Reproducible from a file	Only with the same OS release	Poorly	Reasonably	Yes
Sensible for	A throwaway box	Nothing	A workstation	A shared or CI controller

The rest of this lesson is that table, argued.

The distribution package

Configuration changethe distribution's Ansible— Installs into the system Python via the package manager. Requires root, and the version is whatever the release froze.

sudo apt install ansible-core        # Debian/Ubuntu
sudo dnf install ansible-core        # RHEL/Rocky/Alma

It works, it is signed, it is patched by the distribution’s security process, and it needs no Python knowledge at all. For a throwaway machine, or for a host where Ansible is a convenience rather than the tool that changes production, this is fine.

Its problem is the previous lesson’s problem: the version is a property of your operating system release, not of what you chose. You cannot pin it to what your repository declares, you cannot install two versions to test an upgrade, and upgrading it means upgrading the distribution.

System-wide `pip install ansible` — what actually goes wrong

This is the instruction in every old blog post, and it deserves a straight answer rather than a dismissal.

Configuration changedo not do this on a machine you care about— Installs Ansible and its dependency tree into the distribution-managed system Python. Modern distributions refuse this by default under PEP 668; the flag people reach for to defeat that refusal is named accurately.

sudo pip install ansible                        # refused on a PEP 668 system
sudo pip install --break-system-packages ansible  # and this is why

Three concrete things go wrong.

It shares a dependency tree with the operating system. Distribution tooling is written in Python and imports the same site-packages directory. Ansible pulls in jinja2, cryptography, pyyaml, packaging and resolvelib, and pip will upgrade whichever of those it needs. When the version pip installs is not the version the distribution built its own tools against, the breakage lands somewhere unrelated — the package manager’s Python bindings, a cloud-init hook, a backup agent. The error message will not mention Ansible.

PEP 668 exists precisely because this happened often enough to be worth a standard. On a distribution that implements it, the system Python is marked externally managed and pip refuses. --break-system-packages is not a workaround; it is a switch whose name tells you the outcome.

There is no per-project version. One machine, one Ansible. If two repositories on that controller need different versions — and during any upgrade, they do — you cannot have both.

Upgrades happen to you. pip install --upgrade of anything else on that machine can move a shared dependency underneath Ansible. So can a distribution update that replaces the system Python minor version, which orphans everything pip installed into the old site-packages path. The controller stops working, and nothing in your change log mentions Ansible.

The honest summary: a system-wide pip install ansible produces a controller whose version and dependency set are decided by the interaction of two package managers that do not know about each other. It is not that it never works. It is that when it stops working, the cause is somewhere you would not think to look.

pipx — the workstation answer

pipx installs a Python application into its own private virtualenv and puts the entry-point commands on your PATH. You get ansible, ansible-playbook and the rest as commands, with none of their dependencies visible to anything else.

Configuration changea workstation controller— Creates an isolated environment for ansible-core and links its commands into ~/.local/bin. Nothing is installed into the system Python.

sudo apt install pipx
pipx ensurepath
pipx install 'ansible-core==2.21.3'

Collections are a separate matter — pipx installs the application, not the collections, so ansible-galaxy collection install still runs afterwards. If you need a Python library inside the Ansible environment (a cloud SDK a collection depends on, for instance), pipx inject is the mechanism:

Configuration changea library the collection needs, inside Ansible's environment— Adds a package to the isolated environment pipx created for ansible-core. Without this, a collection that imports boto3 will not find it, because the system boto3 is not on that environment's path.

pipx inject ansible-core boto3

Two versions can coexist with --suffix, which is what makes pipx usable for an upgrade rehearsal:

Configuration changethe new version, alongside the old— Installs a second ansible-core whose commands are named ansible-next, ansible-playbook-next and so on. The existing commands are untouched.

pipx install --suffix=-next 'ansible-core==2.22.0'
ansible-playbook-next --syntax-check site.yml

pipx is the right default for a laptop or a personal jump box. It is weaker for a shared controller because the environment is defined by the commands you ran rather than by a file in the repository, and pipx list is a description of a machine’s history, not a specification.

The explicit virtualenv — the controller answer

A virtualenv is a directory containing an interpreter and a site-packages. You name the Python, you name the versions, and both facts live in your repository.

Configuration changea controller environment you can rebuild— Creates an isolated environment bound to the named interpreter, installs exactly the pinned ansible-core, then confirms what was built. Nothing outside the venv directory is modified.

python3.12 -m venv /opt/estate/venv
/opt/estate/venv/bin/pip install --upgrade pip
/opt/estate/venv/bin/pip install 'ansible-core==2.21.3'
/opt/estate/venv/bin/ansible --version

Confirm what you built rather than assuming it:

Read-only / Safeproving which install is in effect— Read three lines: the core version, the executable location, and the python version. Together they tell you which of the four install paths this shell is actually using.

$ ansible --version

ansible [core 2.21.3]
config file = None
configured module search path = ['/home/ops/.ansible/plugins/modules', '/usr/share/ansible/plugins/modules']
ansible python module location = /opt/estate/venv/lib/python3.14/site-packages/ansible
ansible collection location = /home/ops/.ansible/collections:/usr/share/ansible/collections
executable location = /opt/estate/venv/bin/ansible
python version = 3.14.4 (main, Jun 18 2026, 14:25:02) [GCC 15.2.0] (/opt/estate/venv/bin/python3)
jinja version = 3.1.6
pyyaml version = 6.0.3 (with libyaml v0.2.5)

executable location under /opt/estate/venv is the proof. If it says /usr/bin/ansible, you are running the distribution package regardless of what you installed five minutes ago — the shell resolved ansible from PATH and PATH did not have your venv on it.

The environment is then reproducible from one file:

# requirements.txt
ansible-core==2.21.3

A second machine runs the same three commands, gets the same ansible --version, and the estate has two controllers that agree. That test is the subject of the next lesson.

Under the hood

A virtualenv is much less magic than it looks. python3.12 -m venv DIR creates DIR/bin/python3 (a symlink or a small copy of the interpreter) and DIR/pyvenv.cfg, which records the base interpreter it was built from. When that interpreter starts, it reads pyvenv.cfg, sets sys.prefix to the venv, and therefore looks for packages in DIR/lib/pythonX.Y/site-packages rather than the system one.

Two consequences worth knowing:

The venv is bound to a specific Python minor version. Upgrade the base interpreter from 3.12 to 3.13 and the venv’s lib/python3.12/site-packages is no longer on the new interpreter’s path. The venv does not adapt; it breaks. Rebuilding is the fix, which is cheap if it is scripted and painful if it was done by hand.
pipx is a virtualenv manager. Every pipx install creates exactly the structure above under ~/.local/share/pipx/venvs/ and symlinks the console scripts into ~/.local/bin. The two approaches are the same mechanism with different ergonomics — pipx optimises for commands on your PATH, an explicit venv optimises for a path you can name in a file.

What happens if the controller has two Ansibles and you do not know it?

This is the most common form of “works on my machine”, and it is entirely undramatic: someone installed the distribution package a year ago, someone else built a venv last month, and PATH decides which one a given shell gets.

The symptom is that the same command produces different results depending on who ran it, from which shell, under which shell profile. Cron and CI make it worse, because they start with a minimal PATH that usually resolves to /usr/bin — so the scheduled run uses the distribution package while every interactive test used the venv.

Three commands settle it, and they belong in any controller investigation before you read any YAML:

command -v ansible
ansible --version
ansible-config dump --only-changed

The first tells you which binary PATH chose. The second tells you what that binary is. The third tells you what configuration it will obey. If the answers differ between your shell and the scheduled job, you have found the incident without opening a playbook.

Choosing

For a workstation: pipx. You want commands on your PATH, you want them isolated from the system Python, and you want pipx install --suffix available when it is time to try a new version.

For a shared or CI controller: an explicit virtualenv at a known path, built from a requirements.txt in the repository, invoked by absolute path. Nothing about which version is running should depend on who is logged in.

For neither: a system-wide pip install. There is no situation where it is the best available option, because pipx does the same job without the shared dependency tree.

The blast-radius framing matters here as much as anywhere else in the course. The controller is the machine allowed to change every host you own. An install method that leaves its version ambiguous leaves the behaviour of every scheduled change ambiguous too.