Mitogen¶

Mitogen can accelerate some Ansible runs by replacing the default execution strategy with Mitogen's strategy plugin. It is most useful for many-host, many-task playbooks where connection setup and module transfer overhead are significant.

In a container workflow, install Mitogen in a derived image or mount it into the container, then configure ansible.cfg with strategy_plugins and strategy = mitogen_linear.

Check compatibility

Mitogen must support the ansible-core version in your selected image tag. Test with a small inventory before enabling it in CI or production.

When Mitogen helps¶

Mitogen is worth testing when you have:

many hosts
many short tasks
slow SSH connection setup
high-latency links
repeated deployment runs

It may help less when you have:

one or two hosts
playbooks dominated by long remote commands
cloud API calls from the control node
modules or plugins incompatible with your Mitogen and Ansible versions

Install Mitogen in a derived image¶

FROM willhallonline/ansible:2.21-alpine-3.24

RUN pip install --no-cache-dir mitogen

WORKDIR /ansible

Build:

docker build -t registry.example.com/platform/ansible-mitogen:2.21 .

Check the installed version:

docker run --rm -it registry.example.com/platform/ansible-mitogen:2.21 \
  python -c "import mitogen; print(mitogen.__version__)"

Find the strategy plugin path¶

Use Python inside the same image. The strategy plugin is under the top-level ansible_mitogen package:

docker run --rm -it registry.example.com/platform/ansible-mitogen:2.21 \
  python -c "import ansible_mitogen, os; print(os.path.join(os.path.dirname(ansible_mitogen.__file__), 'plugins', 'strategy'))"

Or inspect package metadata:

docker run --rm -it registry.example.com/platform/ansible-mitogen:2.21 \
  pip show mitogen

Typical paths include:

/usr/lib/python3.12/site-packages/ansible_mitogen/plugins/strategy
/usr/local/lib/python3.12/site-packages/ansible_mitogen/plugins/strategy

Use the path from your image, not a path copied from another host.

Configure ansible.cfg¶

[defaults]
inventory = inventory.ini
strategy_plugins = /usr/local/lib/python3.12/site-packages/ansible_mitogen/plugins/strategy
strategy = mitogen_linear

Run with the Mitogen image:

docker run --rm -it \
  -v $(pwd):/ansible \
  -v ~/.ssh/id_rsa:/home/ansible/.ssh/id_rsa:ro \
  --workdir=/ansible \
  registry.example.com/platform/ansible-mitogen:2.21 \
  ansible-playbook -i inventory.ini site.yml

Use a separate Mitogen config¶

Create ansible-mitogen.cfg when you do not want Mitogen enabled for every run:

[defaults]
inventory = inventory.ini
roles_path = roles
collections_paths = collections
strategy_plugins = /usr/local/lib/python3.12/site-packages/ansible_mitogen/plugins/strategy
strategy = mitogen_linear

Run with ANSIBLE_CONFIG:

docker run --rm -it \
  -v $(pwd):/ansible \
  --workdir=/ansible \
  -e ANSIBLE_CONFIG=/ansible/ansible-mitogen.cfg \
  registry.example.com/platform/ansible-mitogen:2.21 \
  ansible-playbook site.yml

Mount Mitogen for experiments¶

Install Mitogen into a project-local directory on the host:

python -m pip install --target .vendor/mitogen mitogen

Configure Ansible:

[defaults]
strategy_plugins = /ansible/.vendor/mitogen/ansible_mitogen/plugins/strategy
strategy = mitogen_linear

Run with the standard image:

docker run --rm -it \
  -v $(pwd):/ansible \
  --workdir=/ansible \
  willhallonline/ansible:latest \
  ansible-playbook -i inventory.ini site.yml

Note

A derived image is cleaner for CI. A mounted .vendor/ directory is useful for quick compatibility tests.

Verify Mitogen is active¶

Run with verbosity:

docker run --rm -it \
  -v $(pwd):/ansible \
  --workdir=/ansible \
  registry.example.com/platform/ansible-mitogen:2.21 \
  ansible-playbook -i inventory.ini site.yml -vv

Look for Mitogen strategy loading or mitogen_linear in startup output.

Benchmark before adopting¶

Normal run:

time docker run --rm \
  -v $(pwd):/ansible \
  --workdir=/ansible \
  willhallonline/ansible:latest \
  ansible-playbook -i inventory.ini site.yml

Mitogen run:

time docker run --rm \
  -v $(pwd):/ansible \
  --workdir=/ansible \
  -e ANSIBLE_CONFIG=/ansible/ansible-mitogen.cfg \
  registry.example.com/platform/ansible-mitogen:2.21 \
  ansible-playbook site.yml

Benchmark with representative inventories. A localhost-only playbook is not a meaningful test.

Troubleshooting¶

If Ansible cannot find the strategy plugin:

rerun the Python path discovery command inside the same image
check Python version differences between tags
verify ANSIBLE_CONFIG points at the expected file
verify the configured path exists inside the container

If failures happen only with Mitogen enabled:

check Mitogen support for your ansible-core version
run with fewer hosts and -vvv
switch back to strategy = linear to isolate the issue
pin a known-good Mitogen version if needed