Ansible Builder & Execution Environments: Complete Guide (2026)

What Are Execution Environments?

Execution Environments (EEs) are container images that package everything needed to run Ansible automation: ansible-core, Python dependencies, system packages, and collections. They ensure consistent, reproducible automation across development, CI/CD, and production.

See also: Ansible Execution Environments: Build Custom EEs for Enterprise Automation

Why Use Execution Environments?

Traditional Ansible installations suffer from dependency conflicts — different projects need different Python packages, collections, or system libraries. EEs solve this by isolating each automation project in its own container.

Benefits: • Reproducibility — same environment everywhere (laptop, CI/CD, AWX/AAP) • Isolation — no dependency conflicts between projects • Portability — share a single container image with your team • Consistency — development matches production exactly

Install ansible-builder

pip install ansible-builder
# Or install all dev tools
pip install ansible-dev-tools
# Verify
ansible-builder --version

See also: AAP 2.6 Execution Environments: Build, Manage, and Deploy Custom EEs

execution-environment.yml (v3)

The execution-environment.yml file defines what goes into your EE:

---
version: 3
images:
  base_image:
    name: quay.io/ansible/ansible-runner:latest
dependencies:
  galaxy: requirements.yml
  python: requirements.txt
  system: bindep.txt
additional_build_files:
  - src: files/ansible.cfg
    dest: configs
additional_build_steps:
  prepend_galaxy:
    - ADD _build/configs/ansible.cfg /etc/ansible/ansible.cfg
  append_final:
    - RUN echo "Custom EE ready"
options:
  package_manager_path: /usr/bin/dnf

Dependency Files

requirements.yml (Collections)

---
collections:
  - name: amazon.aws
    version: ">=9.0.0"
  - name: community.docker
  - name: community.general
  - name: ansible.posix
  - name: community.vmware

requirements.txt (Python)

boto3>=1.35.0
botocore>=1.35.0
requests>=2.32.0
pyVmomi>=8.0
docker>=7.0
jmespath>=1.0

bindep.txt (System Packages)

gcc [compile]
python3-devel [compile]
libssh-devel [platform:centos-9 platform:rhel-9]
krb5-devel [kerberos]

See also: Build a Custom Ansible Execution Environment Easily

Build Your EE

# Basic build
ansible-builder build --tag my-custom-ee:1.0
# With Podman (default)
ansible-builder build --tag my-ee:latest --container-runtime podman
# With Docker
ansible-builder build --tag my-ee:latest --container-runtime docker
# Verbose output
ansible-builder build --tag my-ee:latest -v 3
# Just generate the Containerfile (don't build)
ansible-builder create --file execution-environment.yml

Use Your EE

With ansible-navigator

# Interactive mode
ansible-navigator run playbook.yml --eei my-custom-ee:latest
# Stdout mode (like ansible-playbook)
ansible-navigator run playbook.yml --eei my-custom-ee:latest --mode stdout
# Pull policy
ansible-navigator run playbook.yml --eei my-custom-ee:latest --pp never

With ansible-navigator Settings

# ansible-navigator.yml
ansible-navigator:
  execution-environment:
    container-engine: podman
    image: my-custom-ee:latest
    pull:
      policy: missing
    volume-mounts:
      - src: /home/user/.ssh
        dest: /home/runner/.ssh
        options: ro
    environment-variables:
      set:
        AWS_PROFILE: production

With AWX / AAP

Push your EE to a container registry:

podman push my-custom-ee:latest quay.io/myorg/my-custom-ee:latest

In AWX/AAP, go to Administration → Execution Environments Add your image URL: quay.io/myorg/my-custom-ee:latest Assign to job templates

Base Images

| Image | Description | |-------|-------------| | quay.io/ansible/ansible-runner:latest | Standard base with ansible-core | | quay.io/ansible/awx-ee:latest | AWX default EE | | registry.redhat.io/ansible-automation-platform-25/ee-minimal-rhel9 | AAP minimal | | registry.redhat.io/ansible-automation-platform-25/ee-supported-rhel9 | AAP supported |

Complete Example: AWS + VMware EE

# execution-environment.yml
---
version: 3
images:
  base_image:
    name: quay.io/ansible/ansible-runner:latest
dependencies:
  galaxy: requirements.yml
  python: requirements.txt
  system: bindep.txt
additional_build_steps:
  append_final:
    - RUN pip install --upgrade pip

# requirements.yml
---
collections:
  - amazon.aws
  - community.vmware
  - community.general
  - ansible.posix
  - ansible.utils

# requirements.txt
boto3>=1.35.0
botocore>=1.35.0
pyVmomi>=8.0
jmespath>=1.0

# Build and test
ansible-builder build --tag aws-vmware-ee:1.0 -v 3
ansible-navigator run test-playbook.yml --eei aws-vmware-ee:1.0 --mode stdout

Troubleshooting

Build fails on dependencies

# Check the generated Containerfile
ansible-builder create
cat context/Containerfile
# Build with verbose
ansible-builder build --tag test:latest -v 3

Collection not found in EE

# Verify collections inside the EE
podman run --rm my-ee:latest ansible-galaxy collection list

Python package conflicts

# Check installed packages
podman run --rm my-ee:latest pip list

Offline/air-gapped builds

# Pre-download collections
ansible-galaxy collection download -r requirements.yml -p ./collections/
# Pre-download Python packages
pip download -r requirements.txt -d ./python-packages/
# Use local files in EE definition

Local Documentation (Offline Reference)

The ansible-builder package doesn't ship man pages. For offline reference:

# Find installed package location
python3 -c "import ansible_builder; print(ansible_builder.__file__)"
# Check for schema files
pip show ansible-builder | grep Location
# Generate a Containerfile to see interpreted fields
ansible-builder create --file execution-environment.yml

FAQ

What's the difference between EE v1, v2, and v3?

Version 3 (current) supports images section, additional_build_files, and improved dependency resolution. Always use v3 for new projects.

Do I need Podman or Docker?

Either works. Podman is the default and recommended (rootless containers). Docker works with --container-runtime docker.

Can I use EEs without ansible-navigator?

Yes — you can run containers directly: podman run --rm -v $(pwd):/runner my-ee:latest ansible-playbook playbook.yml

How do I update an EE?

Update your dependency files, bump the tag version, and rebuild: ansible-builder build --tag my-ee:2.0

Related Articles

• Ansible Creator CLI: Scaffold Collections, Roles & Projects • What Are Ansible Collections • Ansible Docker Complete Guide