{"id":1901,"library":"ansible-compat","title":"Ansible Compat","description":"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.","status":"active","version":"26.3.0","language":"en","source_language":"en","source_url":"https://github.com/ansible-community/ansible-compat","tags":["ansible","compatibility","automation","devops","collection"],"install":[{"cmd":"pip install ansible-compat","lang":"bash","label":"Install latest version"}],"dependencies":[{"reason":"Provides 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.","package":"ansible-core","optional":false}],"imports":[{"symbol":"AnsibleCompatConfig","correct":"from ansible_compat.config import AnsibleCompatConfig"},{"symbol":"AnsibleRuntime","correct":"from ansible_compat.runtime import AnsibleRuntime"},{"symbol":"AnsibleCollectionConfig","correct":"from ansible_compat.primitives import AnsibleCollectionConfig"},{"symbol":"AnsiblePath","correct":"from ansible_compat.primitives import AnsiblePath"}],"quickstart":{"code":"from ansible_compat.config import AnsibleCompatConfig\nfrom ansible_compat.runtime import AnsibleRuntime\nfrom ansible_compat.primitives import AnsiblePath\nimport os\n\n# Initialize configuration (can be empty for defaults, or load from ansible.cfg)\nconfig = AnsibleCompatConfig()\n\n# Initialize runtime, which discovers Ansible paths and settings\nruntime = AnsibleRuntime()\n\nprint(f\"Ansible core version: {runtime.ansible_version}\")\nprint(f\"Ansible config file: {runtime.config_file or 'Not found'}\")\nprint(f\"Ansible collection paths: {runtime.ansible_collection_paths}\")\n\n# Example: Get path for a specific collection\ncollection_name = os.environ.get('ANSIBLE_TEST_COLLECTION', 'community.general')\ncollection_path = runtime.get_collection_path(collection_name)\nif collection_path:\n    print(f\"Collection '{collection_name}' found at: {collection_path}\")\nelse:\n    print(f\"Collection '{collection_name}' not found. Try setting it via ANSIBLE_TEST_COLLECTION.\")\n\n# Example: Using an AnsiblePath primitive\nsome_path = AnsiblePath(\"my_ansible_artifact.yml\")\nprint(f\"AnsiblePath object for 'my_ansible_artifact.yml': {some_path}\")","lang":"python","description":"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."},"warnings":[{"fix":"Migrate to using public methods of the `AnsibleRuntime` class for robust path resolution and interaction with Ansible's loading mechanisms.","message":"Version 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.","severity":"breaking","affected_versions":">=26.0.0"},{"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.","message":"Ansible 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.","severity":"gotcha","affected_versions":">=26.0.0"},{"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.","message":"`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.","severity":"gotcha","affected_versions":"*"},{"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.","message":"When 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.","severity":"gotcha","affected_versions":"*"}],"env_vars":null,"last_verified":"2026-04-09T00:00:00.000Z","next_check":"2026-07-08T00:00:00.000Z"}