Installation Guide How to Install PM4Py
Step-by-step instructions for each system: installing Python and pip, setting up a virtual environment, adding Graphviz for visualizations, and checking that PM4Py works.
Already have Python?
pip install pm4py- Python 3.11 or newer with pip
- Graphviz, to visualize process models
Install PM4Py on Windows
The commands below run in the Command Prompt (cmd) or in PowerShell. If you use Anaconda or Miniconda, run them in the Anaconda Prompt instead.
Install Python and pip
You can install Python directly, or use Anaconda or Miniconda for a managed environment.
Python installer Recommended
- Download the latest Windows installer (64-bit) from python.org.
- Run it and check Add python.exe to PATH on the first screen.
- pip is included.
Check that both are available. Each command prints a version number:
python --versionpip --versionIf pip is missing, download get-pip.py and run
python get-pip.py.Create a virtual environment Recommended
A virtual environment keeps PM4Py and its dependencies apart from other Python projects. Activate it in every new terminal before you work with PM4Py. Navigate to your project folder and run the commands below:
python -m venv pm4py_envpm4py_env\Scripts\activateconda create -n pm4py_env python=3.11conda activate pm4py_envInstall Graphviz
PM4Py draws process models, Petri nets and other visualizations with Graphviz.
- Download the 64-bit EXE installer for Windows from graphviz.org.
- Run it and choose Add Graphviz to the system PATH for all users (or for the current user).
Add Graphviz to the PATH manually
- Find the Graphviz
binfolder, usuallyC:\Program Files\Graphviz\bin. - Open the Start menu, search for Edit the system environment variables and open it.
- Click Environment Variables….
- Under System variables, select Path and click Edit.
- Click New, paste the
binpath and confirm with OK.
Open a new Command Prompt and check the installation:
dot -VIt prints
dot - graphviz version X.XX.Xif Graphviz is set up correctly.Install PM4Py
With your environment activated, run:
pip install pm4pyThis also installs the
graphvizPython package that connects PM4Py to Graphviz.Verify the installation
Import PM4Py and print its version:
python -c "import pm4py; print(pm4py.__version__)"If a version number appears without errors, PM4Py is ready to use.
Install PM4Py on macOS
The commands below run in the Terminal app. The guide uses Homebrew, the most common package manager for macOS.
Install Python and pip
If you do not have Homebrew yet, install it with the command shown on brew.sh. Then install Python, which comes with pip:
brew install pythonCheck that both are available. On macOS they are called
python3andpip3:python3 --versionpip3 --versionPrefer an installer? The macOS installer from python.org works too.
Create a virtual environment
Homebrew's Python does not allow installing packages system-wide (pip reports an
externally-managed-environmenterror), so PM4Py goes into a virtual environment. Activate it in every new terminal before you work with PM4Py. Navigate to your project folder and run the commands below:python3 -m venv pm4py_envsource pm4py_env/bin/activateInside the activated environment,
pythonandpipwork without the 3.Install Graphviz
PM4Py draws process models, Petri nets and other visualizations with Graphviz:
brew install graphvizdot -Vdot -Vprints the Graphviz version if it is set up correctly.Install PM4Py
With your environment activated, run:
pip install pm4pyThis also installs the
graphvizPython package that connects PM4Py to Graphviz.Verify the installation
Import PM4Py and print its version:
python -c "import pm4py; print(pm4py.__version__)"If a version number appears without errors, PM4Py is ready to use.
Install PM4Py on Linux
The commands below run in a terminal. They are given for Ubuntu and Debian (apt) and for Fedora (dnf); other distributions have equivalent packages.
Install Python and pip
Most distributions come with Python 3. Check which version you have:
python3 --versionThen install or update Python, pip and the virtual environment module:
sudo apt updatesudo apt install python3 python3-pip python3-venvsudo dnf install python3 python3-pipCreate a virtual environment
Recent distributions do not allow installing packages into the system Python (pip reports an
externally-managed-environmenterror), so PM4Py goes into a virtual environment. Activate it in every new terminal before you work with PM4Py. Navigate to your project folder and run the commands below:python3 -m venv pm4py_envsource pm4py_env/bin/activateInside the activated environment,
pythonandpipwork without the 3.Install Graphviz
PM4Py draws process models, Petri nets and other visualizations with Graphviz:
sudo apt install graphvizdot -Vsudo dnf install graphvizdot -Vdot -Vprints the Graphviz version if it is set up correctly.Install PM4Py
With your environment activated, run:
pip install pm4pyThis also installs the
graphvizPython package that connects PM4Py to Graphviz.Verify the installation
Import PM4Py and print its version:
python -c "import pm4py; print(pm4py.__version__)"If a version number appears without errors, PM4Py is ready to use.
PM4Py Installation Troubleshooting
The most common problems and how to solve them.
pip is not found
On macOS and Linux, use pip3 outside a virtual environment. On Windows, run the Python installer again and check Add python.exe to PATH. python -m pip works in either case.
externally-managed-environment error
Your system's Python does not accept packages installed with pip. Create and activate a virtual environment (step 2 of the guide for your system) and install PM4Py there.
Graphviz is not found
Visualizations fail with an error such as ExecutableNotFound when the Graphviz program is not on the PATH. Check that dot -V works in a new terminal; on Windows, add the Graphviz bin folder to the PATH as described in step 3.
PM4Py cannot be imported
Make sure the environment you installed PM4Py into is activated. If the error persists, reinstall PM4Py:
pip install --force-reinstall pm4pyNext Steps with PM4Py
PM4Py is installed. Here is where to go from here.
