How to develop and use custom drivers for Molecule?

[DimaZzZz101]

---

Hi everyone,

I'm currently getting into developing custom Molecule drivers, specifically a driver for VMware (in the style of the existing azure or docker drivers), and I have a few questions and observations I’d love some input on.

---

1. How are custom Molecule drivers supposed to be developed?

I've studied the molecule-plugins repository and tried to follow the existing driver patterns (azure, docker, etc.), including:

• Proper Python packaging with entry point under molecule.driver
• cookiecutter directory with scenario templates
• Correct module structure under src/

However, documentation around how to write and test your own custom driver from scratch seems sparse. Is there any maintained guide or best practices available for developing 3rd-party drivers in the Molecule 6 ecosystem?

---

2. Scenario templates from the driver aren't used — why?

Here’s the confusing part.

When I run:

pip install molecule[azure]
molecule init scenario -d azure test_azure

I expect the scenario directory molecule/test_azure/ to contain the driver’s custom scenario templates — as defined in the driver's cookiecutter/{{cookiecutter.molecule_directory}}/... files.

Instead, I get the default Molecule templates, as if the driver was ignored for this part.

Interestingly:

• On Molecule v5.0.1, this worked as expected — driver-specific templates were used.
• On Molecule v6.0.3, this no longer happens, even though the structure in the installed plugin looks correct (i.e., the driver is installed and detected correctly, but not its cookiecutter templates).

I found some commits and changelog entries mentioning changes to plugin handling, including possible temporary removal and re-introduction of this functionality. So I'm wondering:

Has driver-provided cookiecutter scenario support changed or been deprecated in Molecule v6.0.0+?

---

3. Am I doing something wrong?

I’m just getting started with Molecule, and it surprises me that no one else seems to report this. Either I missed something obvious in setup or the community has moved on from this usage pattern?

---

Any help, context, or updated pointers on how to develop and distribute a custom driver (including how scenario templates should be used in v6.x) would be greatly appreciated!

Thanks in advance!

—
P.S.1 If needed, I can share my plugin layout or repro steps.
*P.S.2 This text is auto translated (sorry if something wrong)

---

(.venv) dimazzzz@dz-test:~$ adt --version

ansible-builder                          3.1.0
ansible-core                             2.17.12
ansible-creator                          25.4.1
ansible-dev-environment                  25.5.0
ansible-dev-tools                        25.5.1
ansible-lint                             25.4.0
ansible-navigator                        25.4.1
ansible-sign                             0.1.1
molecule                                 25.4.0
pytest-ansible                           25.4.1
tox-ansible                              25.4.0

(.venv) dimazzzz@dz-test:~$ molecule drivers

vagrant
podman
containers
gce
openstack
docker
default
vmware
ec2
azure

(.venv) dimazzzz@dz-test:~$ tree molecule_molecule_vmware/

molecule_molecule_vmware/
├── build
│   ├── bdist.linux-x86_64
│   └── lib
│       └── molecule_vmware
│           ├── cookiecutter
│           │   ├── cookiecutter.json
│           │   └── {{cookiecutter.molecule_directory}}
│           │       └── {{cookiecutter.scenario_name}}
│           │           ├── converge.yml
│           │           ├── create.yml
│           │           ├── destroy.yml
│           │           └── INSTALL.rst
│           ├── driver.py
│           ├── __init__.py
│           └── _version.py
├── pyproject.toml
├── README.md
└── src
    ├── molecule_vmware
    │   ├── cookiecutter
    │   │   ├── cookiecutter.json
    │   │   └── {{cookiecutter.molecule_directory}}
    │   │       └── {{cookiecutter.scenario_name}}
    │   │           ├── converge.yml
    │   │           ├── create.yml
    │   │           ├── destroy.yml
    │   │           └── INSTALL.rst
    │   ├── driver.py
    │   ├── __init__.py
    │   └── _version.py
    └── molecule_vmware.egg-info
        ├── dependency_links.txt
        ├── entry_points.txt
        ├── PKG-INFO
        ├── requires.txt
        ├── SOURCES.txt
        └── top_level.txt

13 directories, 24 files

(.venv) dimazzzz@dz-test:~$ molecule init scenario test_default

INFO     Initializing new scenario test_default...

PLAY [Create a new molecule scenario] ******************************************

TASK [Check if destination folder exists] **************************************
changed: [localhost]

TASK [Check if destination folder is empty] ************************************
ok: [localhost]

TASK [Fail if destination folder is not empty] *********************************
skipping: [localhost]

TASK [Expand templates] ********************************************************
changed: [localhost] => (item=molecule/test_default/molecule.yml)
changed: [localhost] => (item=molecule/test_default/destroy.yml)
changed: [localhost] => (item=molecule/test_default/create.yml)
changed: [localhost] => (item=molecule/test_default/converge.yml)

PLAY RECAP *********************************************************************
localhost                  : ok=3    changed=2    unreachable=0    failed=0    skipped=1    rescued=0    ignored=0

INFO     Initialized scenario in /home/dimazzzz/molecule/test_default successfully.

(.venv) dimazzzz@dz-test:~$ molecule init scenario -d docker test_docker

INFO     Initializing new scenario test_docker...

PLAY [Create a new molecule scenario] ******************************************

TASK [Check if destination folder exists] **************************************
changed: [localhost]

TASK [Check if destination folder is empty] ************************************
ok: [localhost]

TASK [Fail if destination folder is not empty] *********************************
skipping: [localhost]

TASK [Expand templates] ********************************************************
changed: [localhost] => (item=molecule/test_docker/molecule.yml)
skipping: [localhost] => (item=molecule/test_docker/destroy.yml)
skipping: [localhost] => (item=molecule/test_docker/create.yml)
changed: [localhost] => (item=molecule/test_docker/converge.yml)

PLAY RECAP *********************************************************************
localhost                  : ok=3    changed=2    unreachable=0    failed=0    skipped=1    rescued=0    ignored=0

INFO     Initialized scenario in /home/dimazzzz/molecule/test_docker successfully.

(.venv) dimazzzz@dz-test:~$ molecule init scenario -d azure test_azure

INFO     Initializing new scenario test_azure...

PLAY [Create a new molecule scenario] ******************************************

TASK [Check if destination folder exists] **************************************
changed: [localhost]

TASK [Check if destination folder is empty] ************************************
ok: [localhost]

TASK [Fail if destination folder is not empty] *********************************
skipping: [localhost]

TASK [Expand templates] ********************************************************
changed: [localhost] => (item=molecule/test_azure/molecule.yml)
changed: [localhost] => (item=molecule/test_azure/destroy.yml)
changed: [localhost] => (item=molecule/test_azure/create.yml)
changed: [localhost] => (item=molecule/test_azure/converge.yml)

PLAY RECAP *********************************************************************
localhost                  : ok=3    changed=2    unreachable=0    failed=0    skipped=1    rescued=0    ignored=0

INFO     Initialized scenario in /home/dimazzzz/molecule/test_azure successfully.

(.venv) dimazzzz@dz-test:~$ tree molecule

molecule
├── test_azure
│   ├── converge.yml
│   ├── create.yml
│   ├── destroy.yml
│   └── molecule.yml
├── test_default
│   ├── converge.yml
│   ├── create.yml
│   ├── destroy.yml
│   └── molecule.yml
└── test_docker
    ├── converge.yml
    └── molecule.yml

3 directories, 10 files

(.venv) dimazzzz@dz-test:~$ cat molecule/test_default/molecule.yml

---
driver:
  name: default
platforms:
  - name: instance
    # you might want to add your own variables here based on what provisioning
    # you are doing like:
    # image: quay.io/centos/centos:stream8

(.venv) dimazzzz@dz-test:~$ cat molecule/test_default/converge.yml

---
- name: Converge
  hosts: all
  gather_facts: false
  tasks:
    - name: Replace this task with one that validates your content
      ansible.builtin.debug:
        msg: "This is the effective test"

(.venv) dimazzzz@dz-test:~$ cat molecule/test_default/create.yml

---
- name: Create
  hosts: localhost
  connection: local
  gather_facts: false
  # no_log: "{{ molecule_no_log }}"
  tasks:
    # TODO: Developer must implement and populate 'server' variable

    - name: Create instance config
      when: server.changed | default(false) | bool  # noqa no-handler
      block:
        - name: Populate instance config dict  # noqa jinja
          ansible.builtin.set_fact:
            instance_conf_dict: {}
            # instance': "{{ }}",
            # address': "{{ }}",
            # user': "{{ }}",
            # port': "{{ }}",
            # 'identity_file': "{{ }}", }
          with_items: "{{ server.results }}"
          register: instance_config_dict

        - name: Convert instance config dict to a list
          ansible.builtin.set_fact:
            instance_conf: "{{ instance_config_dict.results | map(attribute='ansible_facts.instance_conf_dict') | list }}"

        - name: Dump instance config
          ansible.builtin.copy:
            content: |
              # Molecule managed

              {{ instance_conf | to_json | from_json | to_yaml }}
            dest: "{{ molecule_instance_config }}"
            mode: "0600"

(.venv) dimazzzz@dz-test:~$ cat molecule/test_default/destroy.yml

---
- name: Destroy
  hosts: localhost
  connection: local
  gather_facts: false
  # no_log: "{{ molecule_no_log }}"
  tasks:
    # Developer must implement.

    # Mandatory configuration for Molecule to function.

    - name: Populate instance config
      ansible.builtin.set_fact:
        instance_conf: {}

    - name: Dump instance config
      ansible.builtin.copy:
        content: |
          # Molecule managed

          {{ instance_conf | to_json | from_json | to_yaml }}
        dest: "{{ molecule_instance_config }}"
        mode: "0600"
      when: server.changed | default(false) | bool  # noqa no-handler

(.venv) dimazzzz@dz-test:~$ cat molecule/test_docker/molecule.yml

---
driver:
  name: docker
platforms:
  - name: instance
    image: quay.io/centos/centos:stream8
    pre_build_image: true

(.venv) dimazzzz@dz-test:~$ cat molecule/test_docker/converge.yml

---
- name: Converge
  hosts: all
  gather_facts: false
  tasks:
    - name: Replace this task with one that validates your content
      ansible.builtin.debug:
        msg: "This is the effective test"

(.venv) dimazzzz@dz-test:~$ cat molecule/test_azure/molecule.yml

---
driver:
  name: azure
platforms:
  - name: instance
    # you might want to add your own variables here based on what provisioning
    # you are doing like:
    # image: quay.io/centos/centos:stream8

(.venv) dimazzzz@dz-test:~$ cat molecule/test_azure/converge.yml

---
- name: Converge
  hosts: all
  gather_facts: false
  tasks:
    - name: Replace this task with one that validates your content
      ansible.builtin.debug:
        msg: "This is the effective test"

(.venv) dimazzzz@dz-test:~$ cat molecule/test_azure/create.yml

---
- name: Create
  hosts: localhost
  connection: local
  gather_facts: false
  # no_log: "{{ molecule_no_log }}"
  tasks:
    # TODO: Developer must implement and populate 'server' variable

    - name: Create instance config
      when: server.changed | default(false) | bool  # noqa no-handler
      block:
        - name: Populate instance config dict  # noqa jinja
          ansible.builtin.set_fact:
            instance_conf_dict: {}
            # instance': "{{ }}",
            # address': "{{ }}",
            # user': "{{ }}",
            # port': "{{ }}",
            # 'identity_file': "{{ }}", }
          with_items: "{{ server.results }}"
          register: instance_config_dict

        - name: Convert instance config dict to a list
          ansible.builtin.set_fact:
            instance_conf: "{{ instance_config_dict.results | map(attribute='ansible_facts.instance_conf_dict') | list }}"

        - name: Dump instance config
          ansible.builtin.copy:
            content: |
              # Molecule managed

              {{ instance_conf | to_json | from_json | to_yaml }}
            dest: "{{ molecule_instance_config }}"
            mode: "0600"

(.venv) dimazzzz@dz-test:~$ cat molecule/test_azure/destroy.yml

---
- name: Destroy
  hosts: localhost
  connection: local
  gather_facts: false
  # no_log: "{{ molecule_no_log }}"
  tasks:
    # Developer must implement.

    # Mandatory configuration for Molecule to function.

    - name: Populate instance config
      ansible.builtin.set_fact:
        instance_conf: {}

    - name: Dump instance config
      ansible.builtin.copy:
        content: |
          # Molecule managed

          {{ instance_conf | to_json | from_json | to_yaml }}
        dest: "{{ molecule_instance_config }}"
        mode: "0600"
      when: server.changed | default(false) | bool  # noqa no-handler