---
id: tox-ansible
version: "26.8.0"
license: MIT
license_treatment: permissive
maintenance: active
---

# tox-ansible — A radical approach to testing ansible content

License: permissive · Maintenance: active · Downloads: 628.6K/mo

## What it is and what it does

tox-ansible is a tox plugin that generates and manages test environments for Ansible collections, automating the matrix of Python versions and Ansible releases you want to validate against. Instead of manually configuring tox environments for each combination, you declare your test scope in pyproject.toml and the plugin dynamically creates sanity, unit, and integration test environments. It delegates the actual testing to ansible-test (for sanity checks) and pytest (for unit and integration tests), leaving environments intact after runs so you can debug failures locally—and ensuring test outcomes match your CI/CD pipeline.

The plugin uses tox to create isolated virtual environments in .tox/, pyyaml and tomli to parse configuration, and pytest-xdist to parallelize test execution. You control which Python versions and Ansible versions to test via simple configuration flags like skip, coverage, and downstream (to include AAP-supported cores). CalVer versioning (YY.MM.MICRO) means releases track the month they ship, and the plugin is actively maintained with support for Python 3.10, 3.11, 3.12, 3.13, and 3.14.

Use it for:

- Test an Ansible collection against multiple Ansible versions and Python interpreters in a single command.
- Run sanity checks on collection code without manually invoking ansible-test, letting tox manage the environment.
- Generate coverage reports for unit tests across collection plugins, with 0% coverage shown for untested files.
- Reproduce CI/CD test failures locally by running the same tox environment names and configurations.
- Skip specific test environments or enable downstream AAP-certified Ansible cores via configuration flags.

## Worth the install?

AI-flagged interpretation of the facts above — verify before relying.

A tox plugin that orchestrates testing of Ansible collections across multiple Python versions and Ansible releases, using ansible-test, pytest, and tox to manage environments.

Yes. If you maintain or test Ansible collections, this plugin eliminates manual environment setup and matrix configuration. Low install friction, active maintenance, no security vulnerabilities, and MIT licensing. The only gotcha is pre-installing the Python versions you want to test—a standard requirement for any multi-version testing tool.

## Install

pip install tox-ansible
uv add tox-ansible
poetry add tox-ansible

## Installing tox-ansible

Before you install: Low friction: pure Python wheel with no compiled dependencies. Active maintenance—released 2 days ago with last commit 2026-08-14. Requires Python >=3.10 and tox >=4.2, plus six runtime test dependencies (pytest, pytest-ansible, pytest-xdist, pyyaml, tomli, tox).

License in practice: MIT license (permissive) imposes no restrictions on use, modification, or distribution in proprietary or open-source projects.

Quickstart:

pip install tox-ansible

# Add to pyproject.toml:
# [tool.tox]
# requires = ["tox>=4.2"]
# [tool.tox-ansible]

# Then run:
tox list --ansible
tox -e sanity-py3.11-2.14 --ansible

Requires tox >=4.2, Python >=3.10, and the specific Python interpreters you want to test against (e.g., python3.11, python3.12) pre-installed on your system.

Verify before relying:

- Whether pytest-ansible and pytest-xdist are automatically installed as transitive deps or must be manually added to your test environment.
- Performance characteristics when running tests in parallel across many Ansible versions and Python interpreters.
- Whether coverage reports work correctly with PyPy in addition to CPython.

## Package facts

- License: MIT (permissive)
- Python support: supports_current
- Install friction: low
- Maintenance: active
- Downloads: 628.6K/month (top 15,000 on PyPI)
- Known vulnerabilities: none known

## Tags

ansible collection testing, tox plugin ansible, multi-version ansible testing, ansible sanity unit integration tests, ansible-core version matrix testing, pytest ansible tox integration, ansible content validation, ansible-testing, tox-plugin, matrix-testing

[View on SkillFed](https://skillfed.io/packages/tox-ansible) · [View on PyPI](https://pypi.org/project/tox-ansible/)