Ansible Development Environment (ade)

26.4.0 · active · verified Wed Apr 15

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.

Common errors

```
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: 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>`.
```
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.
```
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.
```
'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-environment Install directly
pip install ansible-dev-tools Install as part of Ansible Development Tools (recommended)

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

view raw JSON →