Running PyTracerLab Locally

PyTracerLab can be run locally as a Python application — no standalone .exe installer required. This is useful if your IT policy restricts unsigned executables, if you are on a non-Windows platform, or if you simply prefer working from a Python environment.

The steps below walk you through installing Anaconda as a Python distribution, creating a dedicated environment, and launching the GUI. The whole process takes about 10–15 minutes.

Step 1 — Install Anaconda

Anaconda is a free Python distribution bundled with the conda package and environment manager. It is the recommended way to manage Python environments for scientific software like PyTracerLab.

  1. Open https://www.anaconda.com/download in your browser and download the Anaconda Individual Edition installer for your operating system (Windows, macOS, or Linux).

  2. Run the installer and follow the on-screen instructions. The default settings work fine. On Windows, you may be asked whether to add Anaconda to your PATH — keeping the default (not adding to PATH) and using the dedicated Anaconda Prompt application is the safest choice.

  3. After installation, open a terminal:

    • Windows — search for Anaconda Prompt (or Anaconda PowerShell Prompt) in the Start menu and open it.

    • macOS / Linux — open a regular Terminal (conda is initialised in your shell automatically).

  4. Verify the installation by running:

    conda --version

    You should see output such as conda 24.x.x. If you get a command not found error on Windows, make sure you are using the Anaconda Prompt that was installed alongside Anaconda (searchable via the Windows Start menu) rather than a regular Command Prompt or PowerShell window.

Step 2 — Create a Conda Environment

It is best practice to install PyTracerLab into its own isolated environment so that its dependencies do not interfere with other Python projects on your machine.

An environment.yml file is provided in the PyTracerLab repository that sets up a minimal environment with the correct Python version. Download it (or copy its contents into a file named environment.yml) and then run:

conda env create -f environment.yml

This creates a conda environment named pytracerlab. When the command finishes you will see a message confirming that the environment was created.

Tip

The environment only needs to be created once. On subsequent sessions you only need to activate it (Step 3).

Manual setup (alternative)

If you prefer not to use the environment.yml file, create the environment in one command:

conda create -n pytracerlab python=3.11

Step 3 — Activate the Environment

Before installing or running PyTracerLab, activate the environment:

conda activate pytracerlab

Your terminal prompt will change to show (pytracerlab) at the beginning, confirming that the environment is active.

Warning

You need to activate the environment every time you open a new terminal window. Commands run without the environment active will use a different Python installation and will fail with import errors.

Step 4 — Install PyTracerLab

With the pytracerlab environment active, install PyTracerLab from PyPI using pip. This automatically installs PyTracerLab and all of its dependencies (NumPy, SciPy, Matplotlib, PyQt5):

pip install PyTracerLab

You should see output ending with:

Successfully installed PyTracerLab-x.x.x

Step 5 — Launch the GUI

With the environment still active, start the graphical user interface using one of the following commands.

On all platforms (shows a background console window):

PyTracerLab

On Windows (no console window):

PyTracerLab-gui

The PyTracerLab main window should now open. Refer to the GUI usage guide for a description of the individual tabs and the typical workflow.

Updating PyTracerLab

To update to the latest version at any time, activate the environment and run:

pip install --upgrade PyTracerLab

Running from Source (Advanced)

If you want to run the very latest development version — or if you want to modify the source code — you can clone the repository and install from source instead of from PyPI.

1. Get the source code

Clone with Git (recommended):

git clone https://github.com/iGW-TU-Dresden/PyTracerLab.git
cd PyTracerLab

Download as a ZIP archive:

  1. Go to https://github.com/iGW-TU-Dresden/PyTracerLab.

  2. Click the green Code button, then choose Download ZIP.

  3. Extract the ZIP to a folder of your choice and navigate into it in your terminal.

2. Install from source

Follow Steps 1–3 above to install Anaconda and create + activate the pytracerlab environment. Then, from inside the repository folder (the one containing pyproject.toml), run:

pip install -e .

The -e flag (editable mode) makes Python load the package directly from the source files, so any changes you make to the code are reflected immediately without reinstalling.

3. Launch

python src/PyTracerLab/__main__.py

Or, using the entry point registered by pip install -e .:

PyTracerLab-gui

Troubleshooting

conda: command not found or conda is not recognized

On Windows, open Anaconda Prompt from the Start menu instead of a regular Command Prompt or PowerShell. On macOS/Linux, close and reopen your terminal after the Anaconda installation so that the shell initialisation takes effect.

ModuleNotFoundError: No module named 'PyQt5'

This usually means the pytracerlab environment is not active. Run conda activate pytracerlab and try again. If the error persists after activation, reinstall PyTracerLab:

pip install --force-reinstall PyTracerLab

ModuleNotFoundError: No module named 'PyTracerLab'

The package is not installed in the active environment. Run pip install PyTracerLab (or pip install -e . for a source installation) with the environment active.

The GUI window does not appear on Linux

Qt requires a graphical display server. If you are on a headless Linux server (no desktop environment), the GUI cannot be shown. In this case, use PyTracerLab as a Python package in a script or Jupyter notebook instead.