{"id":8328,"library":"molecule-docker","title":"Molecule Docker Driver","description":"Molecule Docker is a driver plugin for Molecule, the Ansible role testing framework. It allows users to test their Ansible roles against Docker containers, providing a lightweight and isolated environment for development and testing. The current version is 2.1.0, and it follows Molecule's release cadence, with major releases aligning with Molecule's major versions and frequent bugfix/minor updates.","status":"active","version":"2.1.0","language":"en","source_language":"en","source_url":"https://github.com/ansible-community/molecule-docker","tags":["ansible","molecule","docker","testing","devops","automation"],"install":[{"cmd":"pip install molecule-docker","lang":"bash","label":"Install latest version"},{"cmd":"ansible-galaxy collection install community.docker","lang":"bash","label":"Install required Ansible collection"}],"dependencies":[{"reason":"Core Molecule framework, version 4.0.0 or newer is required for molecule-docker >= 2.0.0","package":"molecule","optional":false},{"reason":"Ansible engine, version 2.12.0 or newer is required for molecule-docker >= 2.0.0","package":"ansible-core","optional":false},{"reason":"Ansible collection providing Docker modules, version 3.0.0a2 or newer is required for molecule-docker >= 2.0.0","package":"community.docker","optional":false},{"reason":"Python runtime, version 3.8 or newer","package":"python","optional":false}],"imports":[],"quickstart":{"code":"# molecule/default/molecule.yml\n---\ndependency:\n  name: galaxy\ndriver:\n  name: docker\nplatforms:\n  - name: instance\n    image: \"docker.io/pycontribs/centos:8\"\n    pre_build_image: true\nprovisioner:\n  name: ansible\n  playbooks:\n    converge: converge.yml\nverifier:\n  name: ansible\n\n# molecule/default/converge.yml\n---\n- name: Converge\n  hosts: instance\n  tasks:\n    - name: \"Check ping\"\n      ansible.builtin.ping\n","lang":"yaml","description":"To quickly get started, create a `molecule/default/molecule.yml` file and a `molecule/default/converge.yml` file as shown. This configuration specifies the `docker` driver, uses a `pycontribs/centos:8` image, and runs a basic Ansible ping task. After saving these, navigate to the `molecule/default` directory and run `molecule test`."},"warnings":[{"fix":"Upgrade Molecule to 4.x, Ansible Core to 2.12.x+, and use Python 3.8+.","message":"Molecule Docker v2.0.0 introduced significant breaking changes, requiring Molecule 4.0.0+, Ansible Core 2.12.0+, and dropping Python 3.6/3.7 support. Ensure your entire environment is updated.","severity":"breaking","affected_versions":">=2.0.0"},{"fix":"Install the collection using `ansible-galaxy collection install community.docker` and ensure it meets the minimum version requirement.","message":"The `community.docker` Ansible collection is a mandatory runtime dependency for `molecule-docker` 1.0.1 and newer. Specifically, v2.0.0 requires `community.docker>=3.0.0a2`.","severity":"breaking","affected_versions":">=1.0.1"},{"fix":"Upgrade to a newer stable release like 1.0.1 or 2.1.0, or pin to an older stable version if necessary.","message":"Molecule Docker versions 0.3.3 and 0.3.4 were yanked from PyPI due to major regressions. Users should avoid these specific versions.","severity":"gotcha","affected_versions":"0.3.3, 0.3.4"},{"fix":"Upgrade to `molecule-docker` 1.0.1 or newer and install `community.docker`.","message":"Older `molecule-docker` versions (pre-1.0.1) relied on a different Ansible collection or direct modules. Ensure you're using `community.docker` for modern setups.","severity":"gotcha","affected_versions":"<1.0.1"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Upgrade Molecule: `pip install --upgrade molecule`.","cause":"Your installed version of Molecule is too old for molecule-docker 2.x.","error":"The driver \"docker\" requires Molecule v4.0.0 or newer. Found v3.x.x."},{"fix":"Upgrade ansible-core: `pip install --upgrade ansible-core`.","cause":"Your installed version of ansible-core is too old for molecule-docker 2.x.","error":"Ansible requires ansible-core version >= 2.12.0. Current version is 2.11.x."},{"fix":"Install the collection: `ansible-galaxy collection install community.docker`.","cause":"The `community.docker` Ansible collection, which is required by the docker driver, is not installed.","error":"ERROR! The specified collection 'community.docker' was not found in any of the configured collection paths."},{"fix":"Ensure Docker is running and has internet access. Manually pull the image with `docker pull docker.io/pycontribs/centos:8` to diagnose network issues, or correct the image name in `molecule.yml`.","cause":"The specified Docker image in your `molecule.yml` does not exist locally and Docker failed to pull it.","error":"Unable to find image 'docker.io/pycontribs/centos:8' locally"}]}