1. Installation

Follow these steps to install the oq-vmtk package and its dependencies. Note that this procedure implies the installation of the OpenQuake engine dependencies. This procedure was tested on Windows and Linux OS. It is highly recommended to use a virtual environment to install this tool. A virtual environment is an isolated Python environment that allows you to manage dependencies for this project separately from your system’s Python installation. This ensures that the required dependencies for the OpenQuake engine do not interfere with other Python projects or system packages, which could lead to version conflicts.

1.1. Clone the Repository

Open your terminal, and run:

cd <virtual_environment_directory>
git clone https://github.com/GEMScienceTools/oq-vmtk.git
cd oq-vmtk

1.2. Set Up a Virtual Environment

Create a virtual environment to manage dependencies:

python -m venv .venv   # On Windows
python3 -m venv .venv  # On Linux / macOS

Activate the virtual environment:

.venv\Scripts\activate        # On Windows
source .venv/bin/activate     # On macOS
source .venv/Scripts/activate # On Linux

1.3. Install Dependencies

Install the appropriate requirements file based on your operating system and Python version. Pinned-dependency files are provided for Python 3.11, 3.12 and 3.13 on Linux, Windows, and macOS (arm64).

To check your current Python version, run:

python --version

Then pick the matching file. The naming convention is requirements-py<MAJOR><MINOR>-<os>.txt (for example requirements-py312-linux.txt for Python 3.12 on Linux):

# Linux (replace 312 with 311 or 313 to match your Python version)
pip install -r requirements-py312-linux.txt

# Windows
pip install -r requirements-py312-win64.txt

# macOS (arm64)
pip install -r requirements-py312-macos_arm64.txt

The pinned files download large wheels, so slow connections may time out. Pass --timeout=100 to pip install, or, to keep the conventional pip install -r requirements-... command, set the timeout globally once before installing:

pip config set global.timeout 100

1.4. Install the Package

Standard install (recommended for users):

pip install .

Editable / developer install — use this only if you plan to modify the source:

pip install -e .

1.5. Verify the Installation

python -c "import openquake.vmtk; print(openquake.vmtk.__version__)"

This should print the installed version (e.g., 1.2.0). All releases are archived on Zenodo under the concept DOI 10.5281/zenodo.17524871, which always resolves to the latest version.