PM4Py Installation Guidelines

This guide offers detailed, step-by-step instructions for installing PM4Py on both Windows and Linux. It covers all necessary prerequisites, including installing Python, pip, and Graphviz, and concludes with a verification step to confirm that the installation was successful.

Windows

1. Install Python and pip

You can choose between installing Python directly or using Anaconda/Miniconda for a managed environment.

Option 1: Install Python Directly (recommended)
  1. Download Python
    • Visit https://www.python.org/downloads/
    • get the latest Python version (e.g., Python 3.11 or newer) by downloading the corresponding the Windows installer (64-bit or 32-bit)
  2. Install Python
    • Run the installer
    • Make sure to check the box "Add Python to PATH" during installation
    • Select "Customize installation" (optional) to ensure pip is included.
  3. Verify Python and pip
    • Open Command Prompt (cmd) and execute the following commands to verify your Python and pip installations:
      python --version
pip --version
    • If pip is not installed, download get-pip.py, then run: 
      python get-pip.py
Option 2: Install Anaconda or Miniconda
  1. Download Anaconda or Miniconda
  2. Install Anaconda or Miniconda
    • Run the installer and follow the on-screen instructions.
    • Optionally, check the box labeled "Add Anaconda/Miniconda to PATH"—this makes it easier to use Python from any terminal.
    • For Miniconda users: open the Anaconda Prompt for all Conda-related commands.
  3. Verify Python and pip
    • Open the Anaconda Prompt (or Command Prompt, if added to PATH), and run: 
      python --version
pip --version
      These commands should display the installed versions of Python and pip.
  4. Create a Conda Environment (optional but recommended)
    • Create a dedicated Python environment for PM4Py, e.g.: 
      conda create -n pm4py_env python=3.11
    • Activate the environment: 
      conda activate pm4py_env

2. Install Graphviz

To use PM4Py’s visualization features, Graphviz must be installed and properly configured.

  1. Download Graphviz
    Visit the official Graphviz website and download the Windows installer:
    https://graphviz.org/download/
    Look for the installer file named something like graphviz-X.XX.X.msi.
  2. Install Graphviz
    • Run the downloaded installer and follow the on-screen instructions.
    • When prompted, make sure to check the option:
      "Add Graphviz to the system PATH for all users" (or for the current user, if preferred).
    • This ensures that executables like dot.exe can be run from the Command Prompt.
    • If you skipped this step during installation, you can manually add Graphviz to your system PATH (see below).
  3. Manually Add Graphviz to the System PATH (if needed)
    If Graphviz wasn’t added to the PATH during installation, follow these steps:
    • Find the Graphviz bin folder (usually at:
      C:\Program Files\Graphviz\bin or C:\Program Files (x86)\Graphviz\bin).
    • Open the Start menu, search for "Edit the system environment variables", and open it.
    • In the System Properties window, click "Environment Variables...".
    • Under System variables, select "Path" and click "Edit".
    • Click "New", then paste the Graphviz bin path.
    • Click "OK" to apply and save the changes.

    To confirm the setup, open a new Command Prompt and run:

    dot -V
    If the command displays the version (e.g., dot - graphviz version X.XX.X), Graphviz is correctly configured.
  4. Install the Python Graphviz Bindings
    Open Command Prompt (or Anaconda Prompt, if using Conda), and run: 
    pip install graphviz
    This installs the Python package that allows PM4Py to interface with Graphviz.
  5. Verify Graphviz
    To ensure everything is set up correctly, run: 
    dot -V
    If the version information appears without errors, Graphviz is installed and ready to use.

3. Install PM4Py

  1. Install PM4Py
    In Command Prompt (or Anaconda Prompt with the environment activated) run: 
    pip install pm4py
  2. Verify the Installation
    Open a Python shell by running: 
    python
    Once inside the shell, enter the following command: 
    import pm4py
    If no errors are shown, PM4Py has been installed successfully. To exit the shell, type: 
    exit()

Linux Installation

1. Install Python and pip

Most Linux distributions (e.g., Ubuntu, Debian, Fedora) come with Python pre-installed. This guide will help ensure you have the correct Python version and pip installed.

  1. Update Package Manager (Ubuntu/Debian example): Keep your system packages up to date: 
    sudo apt update sudo apt upgrade
  2. Check or Install Python: Verify if Python 3 is already installed: 
    python3 --version
    If Python 3.11 or newer is not installed, install it: 
    sudo apt install python3.11
  3. Install pip: Install pip if it's not already available: 
    sudo apt install python3-pip
    Then verify the installation: 
    pip3 --version
  4. (Optional) Create a Virtual Environment: Install the virtual environment module if needed: 
    sudo apt install python3-venv
    Create and activate a new virtual environment: 
    python3 -m venv pm4py_env source pm4py_env/bin/activate

2. Install Graphviz

  1. Install Graphviz: Use your system's package manager to install Graphviz:
    • On Ubuntu/Debian: 
      sudo apt install graphviz
    • On Fedora: 
      sudo dnf install graphviz
  2. Install the Python Graphviz Bindings: With your virtual environment activated (or globally, if preferred), install the Python package: 
    pip3 install graphviz
  3. Verify the Installation: Check if Graphviz is properly installed by running: 
    dot -V
    If it prints the version information without errors, the installation was successful.

3. Install PM4Py

  1. Install PM4Py: With your virtual environment activated (or globally, if preferred), install PM4Py by running: 
    pip3 install pm4py
  2. Verify the Installation: Launch a Python shell: 
    python3
    Then enter the following command: 
    import pm4py
    If no errors are displayed, PM4Py is installed successfully. Exit the Python shell with: 
    exit()

Troubleshooting

  • pip not found: Make sure pip is installed. On Linux, use pip3 instead of pip.
  • Graphviz not found: Check that Graphviz is installed and added to your system's PATH (on Windows), and that the Python graphviz package is also installed.
  • pm4py import errors: Ensure all required dependencies (like Graphviz) are installed. You can try reinstalling pm4py using: 
    pip install --force-reinstall pm4py
  • Conda issues: If you're using Anaconda or Miniconda, make sure the correct environment is activated before installing packages.
PIS Logo