This document assumes the developer has a basic understanding of python packaging, and how to install and manage python on the system executing Molecule.


Depending on the driver chosen, you may need to install additional OS packages. See INSTALL.rst, which is created when initializing a new scenario.

  • Python 2.7 or Python >= 3.5 with Ansible >= 2.5

CentOS 7

$ sudo yum install -y epel-release
$ sudo yum install -y gcc python-pip python-devel openssl-devel libselinux-python

Ubuntu 16.x

$ sudo apt-get update
$ sudo apt-get install -y python-pip libssl-dev


pip is the only supported installation method.

Keep in mind that on selinux supporting systems, if you install into a virtual environment, you may face issue even if selinux is not enabled or is configured to be permissive.

It is your reponsability to assure that soft dependencies of Ansible are available on your controller or host machines.


It is highly recommended that you install molecule in a virtual environment. This will provide a modern copy of setuptools which is mandatory in order for molecule to be installed successfully and function correctly. If you cannot use a virtual environment then you can attempt a package upgrade with the following:

$ pip install --upgrade --user setuptools


Pip v19 series has an isolation bug of setuptools being exposed to the package build env. That is why it’s highly recommended to upgrade user setuptools even when using a proper virtualenv as shown above.


Depending on the driver chosen, you may need to install additional python packages. See the driver’s documentation or INSTALL.rst, which is created when initializing a new scenario.


Install Molecule:

$ pip install --user molecule

Installing molecule package also installed its main script molecule, usually in PATH. Users should know that molecule can also be called as a python module, using python -m molecule .... This alternative method has some benefits:

  • allows to explicitly control which python interpreter is used by molecule

  • allows molecule installation at user level without even needing to have the script in PATH.


We also have a continuous pre-release process which is provided for early adoption and feedback purposes only. It is available from and can be installed like so:

pip install \
  --index-url \
  --extra-index-url \

Where 2.21.dev46 is the latest available pre-release version. Please check the release history listing for the available releases.


We publish molecule images via where the following tags are available:

  • latest: latest master branch build, which should be viewed as unstable

  • 2.20: Git based tags

  • 2.20a1: Pre-releases tags

Please see the tags listing for available tags.

Please see Docker for usage.


Due to the rapid pace of development on this tool, you might want to install and update a bleeding-edge version of Molecule from Git.

Follow the instructions below to do the initial install and subsequent updates.

The package distribution that you’ll get installed will be autogenerated and will contain a commit hash information making it easier to refer to certain unstable version should the need to send a bug report arise.


Please avoid using --editable/-e development mode when installing Molecule with Pip. This not very well supported and only needed when doing development. For contributing purposes, you can rely on the tox command line interface. Please see our testing guide for further details.


CentOS 7

$ sudo yum install -y libffi-devel git

Ubuntu 16.x

$ sudo apt-get install -y libffi-dev git


$ pip install -U git+