Installation

Choose the desktop application for GUI workflows, or install the Python package for scripts and pipelines. Running from source also gives you access to the GUI and the bundled examples.

Desktop application

Download the asset for your platform from the releases page:

• Windows: download and run z-rad-<release-tag>-windows.exe.

• Apple Silicon macOS: download z-rad-<release-tag>-macos-arm64.zip, extract it, and open Z-Rad.app.

The macOS app is unsigned and unnotarized, so macOS may show a Gatekeeper warning. Intel Mac and Linux users can run the GUI from source as described below. The packaged application does not require a separate Python installation.

Continue with GUI quickstart once the application opens.

Python environment

Python workflows require Python 3.11 or newer on Windows, macOS, or Linux. Choose one route: install the published package for your own scripts, or follow Run from source for this documentation’s bundled quickstart and source GUI. For the source route, clone first and create the environment inside the checkout. Reuse an existing environment if you have already set it up.

Create a virtual environment in your working directory (use python3 if that is how your system names the supported interpreter):

python -m venv .venv

Activate it on macOS or Linux:

source .venv/bin/activate

Or in Windows PowerShell:

.venv\Scripts\Activate.ps1

Install the package

For use in your own scripts, install the published package in the activated environment:

python -m pip install z-rad

Continue with Python image workflows to use your own images. For a first run with bundled data and a known result, Python API quickstart uses a source checkout; follow the source route below instead of installing both ways.

Run from source

Clone the repository, or download and extract its source archive:

git clone https://github.com/medical-physics-usz/z-rad.git
cd z-rad

Create and activate a Python environment as described above, then install from the repository root:

python -m pip install -e .

The editable installation uses this checkout for imports. Continue with Python API quickstart for Python extraction. To start the GUI, run:

python main.py

If you only need a non-editable package installation from source, use python -m pip install . instead.