Ansible Development Environment (ade)

26.4.0 verified Wed Apr 15 auth: no python

Ansible Development Environment (ade) is a command-line tool designed to manage isolated virtual environments for Ansible content development. It simplifies the installation and removal of Ansible collections, handles Python dependency resolution for collections, and ensures consistent and reproducible development workspaces. As of version 26.4.0, it promotes an "ephemeral" development approach and is typically released as part of the broader `ansible-dev-tools` package, which has a regular maintenance and release cadence.

pip install ansible-dev-environment

Common errors

error Error: Collections found in /usr/share/ansible/collections Hint: Run `sudo rm -rf /usr/share/ansible/collections` to remove them. ↓

cause This error occurs when system-wide Ansible collections are present, which can interfere with the isolated environment that `ansible-dev-environment` aims to create.

fix

Remove the system-wide collections by running sudo rm -rf /usr/share/ansible/collections.

error Error: Unable to use user site packages directory: /root/.local/lib/python3.13/site-packages, please activate or specify a virtual environment Hint: Use `--venv <directory>` to specify a virtual environment or enable an existing one. ↓

cause This error indicates that `ansible-dev-environment` cannot use the user site-packages directory because a virtual environment is not activated or specified.

fix

Activate an existing virtual environment using source <venv>/bin/activate or specify one during installation with --venv <directory>.

error Critical: The development environment is not isolated, please resolve the above errors. ↓

cause This critical error occurs when the development environment is not properly isolated, often due to the presence of system-wide collections or the absence of a virtual environment.

fix

Ensure that system-wide collections are removed and a virtual environment is activated or specified to achieve an isolated development environment.

error ade: command not found ↓

cause The `ade` executable, installed via `pip` or similar, is located in a directory that is not included in the system's PATH environment variable, making it unlocatable by the shell. This commonly occurs when `pip install --user` puts executables in `~/.local/bin`.

fix

Add the directory where ade is installed (e.g., ~/.local/bin) to your system's PATH environment variable. For Bash or Zsh, add export PATH="$HOME/.local/bin:$PATH" to your ~/.bashrc or ~/.zshrc file and then source the file.

error 'source' is not recognized as an internal or external command, operable program or batch file. ↓

cause This error occurs on Windows when attempting to activate a Python virtual environment using the `source` command, which is a Unix/Linux shell command and not available in Windows Command Prompt or PowerShell.

fix

On Windows, activate the virtual environment using its specific activation script. For Command Prompt, use .\venv\Scripts\activate.bat. For PowerShell, use .\venv\Scripts\Activate.ps1 (you might need to adjust your execution policy for PowerShell scripts: Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser).

Warnings

gotcha Ansible's collection search path behavior can lead to 'workspace pollution' where global collections override those in your virtual environment. This can cause silent version conflicts, inconsistent behavior, and debugging nightmares. ↓

fix `ade` (ansible-dev-environment) addresses this by installing collections into the virtual environment's site-packages and using isolation modes (like `cfg` which modifies `ansible.cfg` in the current directory with `collections_path = .`) to ensure the correct collection versions are used. Avoid using the `none` isolation mode for development.

breaking While `ansible-dev-environment` itself generally focuses on environment management and less on direct API breaking changes, its functionality is tightly coupled with `ansible-core` and Ansible collections. Major releases of the broader Ansible community package (which `ansible-dev-environment` is part of conceptually, and often installed via `ansible-dev-tools`) can contain breaking changes in modules, plugins, and core features, following semantic versioning. ↓

fix Refer to the Ansible Porting Guides and changelogs for `ansible-core` and specific collections when upgrading. Validate your content to ensure compatibility with new templating changes or other behavioral shifts.

gotcha `ansible-dev-environment` requires Python 3.10 or later. Using older Python versions will result in installation failures or unexpected behavior. ↓

fix Ensure your development environment uses Python 3.10 or a newer compatible version. Check `python3 --version` before installation.

Install

pip install ansible-dev-tools

Imports

ade

This library is primarily a command-line interface (CLI) tool. Direct Python imports for programmatic use are not a common pattern as its functionality is exposed via the `ade` command.

ansible-dev-environment is a CLI tool, not typically imported as a Python library for direct programmatic use.

Quickstart

This quickstart demonstrates how to set up an isolated development environment for an Ansible collection using `ade`. It clones a sample collection, installs it in editable mode within a dedicated virtual environment, and then activates that environment for further development.

# Assuming you have a Git repository for your Ansible collection
# git clone https://github.com/your_namespace/your_collection.git
# cd your_collection

ade install -e . --venv .venv
# The above command creates a virtual environment '.venv' and installs
# your collection in editable mode, along with its dependencies.
# It also sets up isolation to prevent collection search path pollution.

source .venv/bin/activate

# Now you can use ansible-playbook, ansible-test, pytest, etc.,
# with the isolated environment and your collection.
ansible-galaxy collection list