Registry / devops / ansible-compat

ansible-compat

JSON →
library26.8.0pypypi✓ verified 24d ago

Ansible Compat is a Python library providing essential compatibility layers and utilities for Ansible projects, primarily benefiting Ansible collection developers. It helps in managing forward and backward compatibility across different Ansible core versions by abstracting away API differences and simplifying interactions with Ansible's runtime. The current version is 26.3.0, and releases are typically aligned with major Ansible core updates or significant feature enhancements.

pip install ansible-compat
INSTALL
IMPORT
SIG · ANSIBLE-COMPAT
A
ansible-compat
devopspythonv26.8.0
Install
5.0s avg
Import
112ms
Disk
61MB
Pass rate
10/ 10
Env Coverage10 / 10
glibc
3.93.13
musl
3.93.13
Install & Compatibility
Where this runs
tested against v26.8.0 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
py 3.103.95 runs
installs and imports cleanly · install 0.0s · import 0.126s · 59.6MB
glibc
py 3.103.95 runs
installs and imports cleanly · install 5.0s · import 0.098s · 60MB
61MB installed
● package 61MB
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

PackageNotFoundError
from ansible_compat import PackageNotFoundError
from ansible_compat.config import AnsibleCompatConfig
version
from ansible_compat import version
from ansible_compat.config import AnsibleCompatConfig

This quickstart demonstrates how to initialize `AnsibleCompatConfig` and `AnsibleRuntime` to access Ansible's configuration and runtime environment. It shows how to query the Ansible version, configuration file path, collection paths, and find a specific collection. It also includes an example of using the `AnsiblePath` primitive.

from ansible_compat.config import AnsibleCompatConfig from ansible_compat.runtime import AnsibleRuntime from ansible_compat.primitives import AnsiblePath import os # Initialize configuration (can be empty for defaults, or load from ansible.cfg) config = AnsibleCompatConfig() # Initialize runtime, which discovers Ansible paths and settings runtime = AnsibleRuntime() print(f"Ansible core version: {runtime.ansible_version}") print(f"Ansible config file: {runtime.config_file or 'Not found'}") print(f"Ansible collection paths: {runtime.ansible_collection_paths}") # Example: Get path for a specific collection collection_name = os.environ.get('ANSIBLE_TEST_COLLECTION', 'community.general') collection_path = runtime.get_collection_path(collection_name) if collection_path: print(f"Collection '{collection_name}' found at: {collection_path}") else: print(f"Collection '{collection_name}' not found. Try setting it via ANSIBLE_TEST_COLLECTION.") # Example: Using an AnsiblePath primitive some_path = AnsiblePath("my_ansible_artifact.yml") print(f"AnsiblePath object for 'my_ansible_artifact.yml': {some_path}")
Debug
Known issues
breakingVersion 26.0.0 introduced significant internal refactoring related to collection and role loading logic, specifically adapting to changes in `ansible-core` 2.15+. Code that relied on direct access to internal path attributes (e.g., `_ansible_collection_path`) may no longer work.
fix
Migrate to using public methods of the `AnsibleRuntime` class for robust path resolution and interaction with Ansible's loading mechanisms.
affects: >=26.0.0
gotchaAnsible Compat has tight Python version requirements, which can also be influenced by its `ansible-core` dependency. For `ansible-compat` 26.x, Python 3.10+ is required.
fix
Always ensure your Python environment meets the minimum version specified in the `ansible-compat` project's `pyproject.toml` or documentation, as well as the requirements of the `ansible-core` version you intend to use.
affects: >=26.0.0
gotcha`ansible-compat` is highly dependent on `ansible-core`. Using mismatched versions (e.g., `ansible-compat` expecting `ansible-core` 2.15+ but finding an older version) can lead to runtime errors or unexpected behavior.
fix
Refer to the `ansible-compat` documentation or its `pyproject.toml` for the supported range of `ansible-core` versions and install a compatible `ansible-core` release.
affects: *
gotchaWhen working in non-standard Ansible environments (e.g., custom `ansible.cfg` locations, unique collection paths, or isolated virtual environments), `AnsibleRuntime` and `AnsibleCompatConfig` might not automatically discover all desired settings by default.
fix
Explicitly pass relevant configuration paths or set standard Ansible environment variables (e.g., `ANSIBLE_CONFIG`, `ANSIBLE_COLLECTIONS_PATH`) before initializing `AnsibleCompatConfig` or `AnsibleRuntime` to ensure proper discovery.
affects: *
Upgrade
Version history
26.8.0latest on PyPI · released Aug 12, 2026
Audit
Dependencies
ansible-corerequiredProvides the underlying Ansible APIs and runtime environment that ansible-compat extends and abstracts. Specific versions are required based on ansible-compat's own version requirements.
Agent activity
28 hits · last 30 days
node
24
OpenAI (training)
1
Resources
ansible-compat — pip install ansible-compat · libregistry