A environment management tool for Ansible content development that provides isolated workspaces for development. ansible-dev-environment (ade) manages virtual environments, collection installation and removal, and Python dependency resolution to ensure consistent, reproducible development environments.

ansible-dev-environment (ade) provides comprehensive collection development environment management by:

• Creating isolated virtual environments
• Installing and removing collections with full dependency tracking
• Resolving and installing collection Python dependencies from requirements.txt and test-requirements.txt
• Installing collections in editable mode with symlinks for active development
• Managing development dependencies like ansible-dev-tools
• Providing configurable workspace isolation

While ansible-galaxy efficiently manages collection installation and dependencies, it does not handle Python package dependencies that collections may require. ade complements this by ensuring all Python requirements are properly managed within isolated environments.

Collections are installed into Python's site-packages directory, making them discoverable by both Ansible and Python tooling including pytest.

Modern Ansible collection development requires isolation to prevent conflicts between projects with different dependency requirements. Each collection project may require:

• Different Python package versions (e.g., requests==2.25.0 vs requests==2.31.0)
• Different Ansible core versions (ansible-core>=2.15 vs ansible-core<2.17)
• Different collection dependencies that may have conflicting requirements
• Different Python interpreter versions

ade addresses these challenges by creating project-specific virtual environments where both Python packages and Ansible collections are installed. This approach offers several advantages:

• Complete isolation: Each project has its own dependency space
• Reproducible environments: Consistent development setup across team members
• Safe experimentation: Virtual environments can be destroyed and recreated without affecting other projects
• Version control friendly: Virtual environments are typically excluded from git repositories, keeping repos clean
• Python version flexibility: Each project can specify its required Python version

By installing collections into the virtual environment's site-packages (rather than global Ansible paths), collections become part of the disposable development environment, eliminating the "dependency hell" common in shared collection spaces.

A critical issue in Ansible collection development is workspace pollution caused by Ansible's collection search path behavior. Ansible searches for collections in this priority order:

1. Paths in ANSIBLE_COLLECTIONS_PATHS environment variable
2. ~/.ansible/collections (user collections directory)
3. /usr/share/ansible/collections (system collections directory)
4. Virtual environment site-packages (when properly configured)

When collections exist in higher-priority locations, they override collections in your virtual environment, leading to:

• Silent version conflicts: Your venv may contain community.general 5.8.0, but Ansible uses community.general 4.2.0 from ~/.ansible/collections
• Inconsistent behavior: Code works on one developer's machine but fails on another due to different global collections
• Debugging nightmares: Test failures that appear unrelated to your changes, caused by different collection versions being loaded
• Development confusion: Modified collection code has no effect because Ansible loads an older version from a global location

For example, if you're developing community.crypto and have an older version installed globally:

# Your development setup ls .venv/lib/python3.11/site-packages/ansible_collections/community/crypto/ # Contains your latest changes # But Ansible finds this first ls ~/.ansible/collections/ansible_collections/community/crypto/ # Contains an older version that overrides your work

This is why ade provides isolation modes:

• cfg mode: Creates ansible.cfg with collections_path = . to prioritize the current workspace
• restrictive mode: Fails fast if global collections are detected, forcing cleanup
• none mode: Allows pollution (not recommended for development)

Proper isolation ensures that ansible-playbook, ansible-test, and pytest all use the exact collection versions installed in your virtual environment, making development predictable and reproducible.

Install using uv (recommended):

uv tool install ansible-dev-environment

Alternative installation methods:

pip install ansible-dev-environment # or pipx install ansible-dev-environment

Create an isolated development environment for a collection:

git clone https://github.com/namespace/collection-name cd collection-name ade install -e . --venv .venv

$ ade --help usage: ade [-h] [--ansi | --no-ansi] [--lf LOG_FILE] [--ll {notset,debug,info,warning,error,critical}] [--la {true,false}] [--uv | --no-uv] [-v] [-V] ... A pip-like ansible collection installer. Commands: check Check installed collections inspect Inspect installed collections list List installed collections tree Generate a dependency tree install Install a collection uninstall Uninstall a collection 

$ ade install --help usage: ade install [-h] [--venv <directory>] [--cpi] [--ssp] [-r REQUIREMENT] [--acv ANSIBLE_CORE_VERSION] [-e] [-p PYTHON] [--seed | --no-seed] [--im {restrictive,cfg,none}] [--uv | --no-uv] [-v] [collection_specifier ...] Options: --venv <directory> Target virtual environment (default: .venv) -e, --editable Install in editable mode (development) -r, --requirement <file> Install from requirements file -p, --python Python interpreter for virtual environment (version, name, or path) --seed / --no-seed Install ansible-dev-tools (default: true) --im, --isolation-mode Isolation mode (choices: restrictive, cfg, none) --acv Ansible core version constraint --uv / --no-uv Use uv package manager if available (default: true) 

# Use Python 3.11 specifically ade install -e . --venv .venv --python python3.11 # Use Python by version number ade install -e . --venv .venv --python 3.12 # Use specific Python path ade install -e . --venv .venv --python /usr/bin/python3.10

ade provides three isolation modes to prevent collection conflicts:

• cfg (default): Creates/updates ansible.cfg in the current directory with collections_path = . to isolate the workspace
• restrictive: Exits if collections are found in system locations (~/.ansible/collections, /usr/share/ansible/collections)
• none: No isolation (not recommended for development)

Install a collection in editable mode:

ade install -e . --venv .venv

Example output:

Info: uv is available and will be used instead of venv/pip Info: Found collection name: example.demo from ./galaxy.yml Note: Created virtual environment: .venv Info: Installing ansible-dev-tools Info: Installing python requirements from ./requirements.txt Info: Installing python requirements from ./test-requirements.txt Info: Installing ansible-core Info: Installing collection dependencies Info: Installing local collection: example.demo 

ade install -r requirements.yml --venv .venv

ade install -e . --venv .venv --acv 2.18.0

ade list --venv .venv

ade tree --venv .venv

Configure behavior via environment variables:

export ADE_PYTHON=python3.12 # Python interpreter export ADE_UV=false # Disable uv usage export ADE_ISOLATION_MODE=cfg # Set isolation mode export ADE_VERBOSE=2 # Verbosity level export ADE_ANSIBLE_CORE_VERSION=2.18.0 # Ansible core version

ade can create virtual environments using either Python's built-in venv or uv (when available). When uv is detected, it's used automatically for faster environment creation and package installation.

To activate the created environment:

source .venv/bin/activate # Linux/macOS

With cfg isolation mode (default), ade creates or updates ansible.cfg:

[defaults] collections_path = .

This ensures Ansible only discovers collections from the current workspace.

ade processes these requirement files when present:

• requirements.txt - Runtime Python dependencies
• test-requirements.txt - Development/testing dependencies
• requirements.yml - Collection dependencies (processed by ansible-galaxy)

If using restrictive mode and seeing isolation errors:

# Remove system collections sudo rm -rf /usr/share/ansible/collections # Clear user collections rm -rf ~/.ansible/collections # Unset collection path variables unset ANSIBLE_COLLECTIONS_PATHS ANSIBLE_COLLECTION_PATH

Ensure the virtual environment is activated after installation:

source .venv/bin/activate

• ansible-galaxy: Collection management and installation
• ansible-dev-tools: Development tooling suite for Ansible content creators
• uv: Fast Python package installer and resolver