{"id":6511,"library":"ansible-dev-environment","title":"Ansible Development Environment (ade)","description":"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.","status":"active","version":"26.4.0","language":"en","source_language":"en","source_url":"https://github.com/ansible/ansible-dev-environment","tags":["ansible","development","environment management","collections","virtualenv","cli","tooling"],"install":[{"cmd":"pip install ansible-dev-environment","lang":"bash","label":"Install directly"},{"cmd":"pip install ansible-dev-tools","lang":"bash","label":"Install as part of Ansible Development Tools (recommended)"}],"dependencies":[{"reason":"Runtime requirement, specifically Python 3.10 or later.","package":"python","optional":false},{"reason":"Core Ansible functionality, often installed as a dependency or alongside `ade`.","package":"ansible-core","optional":true},{"reason":"Used for performance boost in virtual environment management, if available. Can be disabled with `SKIP_UV=1`.","package":"uv","optional":true}],"imports":[{"note":"ansible-dev-environment is a CLI tool, not typically imported as a Python library for direct programmatic use.","symbol":"ade","correct":"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."}],"quickstart":{"code":"# Assuming you have a Git repository for your Ansible collection\n# git clone https://github.com/your_namespace/your_collection.git\n# cd your_collection\n\nade install -e . --venv .venv\n# The above command creates a virtual environment '.venv' and installs\n# your collection in editable mode, along with its dependencies.\n# It also sets up isolation to prevent collection search path pollution.\n\nsource .venv/bin/activate\n\n# Now you can use ansible-playbook, ansible-test, pytest, etc.,\n# with the isolated environment and your collection.\nansible-galaxy collection list","lang":"bash","description":"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."},"warnings":[{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","severity":"breaking","affected_versions":"Dependent on `ansible-core` and collection versions. Be cautious when upgrading major versions of `ansible-core` or collections."},{"fix":"Ensure your development environment uses Python 3.10 or a newer compatible version. Check `python3 --version` before installation.","message":"`ansible-dev-environment` requires Python 3.10 or later. Using older Python versions will result in installation failures or unexpected behavior.","severity":"gotcha","affected_versions":"<26.0.0 (and potentially earlier major versions)"}],"env_vars":null,"last_verified":"2026-04-15T00:00:00.000Z","next_check":"2026-07-14T00:00:00.000Z","problems":[{"fix":"Remove the system-wide collections by running `sudo rm -rf /usr/share/ansible/collections`.","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.","error":"Error: Collections found in /usr/share/ansible/collections\nHint: Run `sudo rm -rf /usr/share/ansible/collections` to remove them."},{"fix":"Activate an existing virtual environment using `source <venv>/bin/activate` or specify one during installation with `--venv <directory>`.","cause":"This error indicates that `ansible-dev-environment` cannot use the user site-packages directory because a virtual environment is not activated or specified.","error":"Error: Unable to use user site packages directory: /root/.local/lib/python3.13/site-packages, please activate or specify a virtual environment\nHint: Use `--venv <directory>` to specify a virtual environment or enable an existing one."},{"fix":"Ensure that system-wide collections are removed and a virtual environment is activated or specified to achieve an isolated development environment.","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.","error":"Critical: The development environment is not isolated, please resolve the above errors."},{"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.","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`.","error":"ade: command not found"},{"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`).","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.","error":"'source' is not recognized as an internal or external command, operable program or batch file."}]}