2.2. Creating a Python Environment

Table of Contents

Virtual environments

For GATE you will write Python scripts, install scientific libraries, and update packages over time. To keep things clean and avoid conflicts with other Python projects on your computer, you should always work inside an isolated Python environment.

A virtual environment is an independent Python installation that lives inside a folder. It has its own interpreter and its own set of installed packages. Changing packages in one virtual environment does not affect other projects or your system Python.

On most systems you can create a virtual environment using the Python built in venv module. First check which python you will use. On Linux and macOS, in a terminal:

bash

python3 --version

On Windows, you may have python or py:

bat

python --version

Once you know the command, create a new environment. Choose a project directory and from inside it run, for example:

bash

python3 -m venv gate_env

This creates a folder named gate_env that contains the environment.

To use it, you must activate it every time you open a new terminal.

On Linux and macOS:

bash

source gate_env/bin/activate

On Windows PowerShell:

powershell

gate_env\Scripts\Activate.ps1

On Windows Command Prompt:

bat

gate_env\Scripts\activate.bat

After activation your terminal prompt usually shows (gate_env) at the beginning. Once active, any pip install will install into this environment only.

Install typical scientific packages for GATE work, for example:

bash

pip install --upgrade pip
pip install numpy matplotlib scipy

You will install GATE related Python packages later in the installation chapter, but they will also go inside this environment.

When you finish working, you can leave the environment with:

bash

deactivate

You can create separate virtual environments for different GATE versions or different projects, which helps when you follow tutorials that require a specific set of packages.

Always activate the correct virtual environment before installing or running GATE related Python code. Installing packages without an active environment can place them into system Python and cause version conflicts or permission issues.

Conda environments

Conda is an alternative way to manage Python versions and packages. It is especially helpful on Windows and for complex scientific software, because it provides precompiled binaries for many libraries.

If you use Anaconda or Miniconda, you will work with conda environments instead of venv. A conda environment is also an isolated Python environment, but conda manages both Python itself and many compiled dependencies.

After installing Miniconda or Anaconda and opening a terminal or Anaconda Prompt, check conda:

bash

conda --version

To create a new environment for GATE, choose a name and a Python version. For example:

bash

conda create -n gate_env python=3.11

Conda will show a list of packages to install and ask for confirmation.

Activate the environment:

bash

conda activate gate_env

Your prompt will show (gate_env). Inside this environment you can install Python packages either with conda or with pip.

For basic scientific tools you might use:

bash

conda install numpy scipy matplotlib

or, if you prefer, use pip while the conda environment is active:

bash

pip install numpy scipy matplotlib

Later, when instructions say pip install opengate or similar, you should still activate this conda environment first, then run the install commands.

To leave the environment:

bash

conda deactivate

You can list all your conda environments with:

bash

conda env list

You can remove an environment you no longer need with:

bash

conda remove -n gate_env --all

For GATE you normally need exactly one main scientific environment on a given machine. If you test different GATE or Geant4 builds, you may decide to create multiple conda environments and keep each configuration separate.

Do not mix many different conda and pip installations at system level. Always conda activate the intended environment before installing GATE and related libraries, to avoid broken or inconsistent setups.

Managing dependencies

Dependencies are all the external packages your GATE simulation scripts rely on, such as NumPy, Matplotlib, or the Python interface to GATE itself. Managing these dependencies carefully makes your simulations repeatable and easier to share.

Inside your virtual or conda environment, you typically install dependencies with pip or conda. For example:

bash

pip install numpy matplotlib

bash

conda install numpy matplotlib

Over time, you may forget which versions you installed. To keep track you should record them in a file, commonly named requirements.txt for pip based workflows.

With your environment activated, you can save all currently installed packages and versions:

bash

pip freeze > requirements.txt

This file might contain lines like:

text

numpy==1.26.4
matplotlib==3.9.0
scipy==1.14.0
opengate==X.Y.Z

Later, on another computer or after recreating the environment, you can install the same versions with:

bash

pip install -r requirements.txt

With conda, you can export a more complete environment description, including Python and all conda managed packages:

bash

conda env export > environment.yml

This environment.yml file can be used to recreate the environment:

bash

conda env create -f environment.yml

For a GATE project, it is good practice to keep one dependency file with the project in version control. That way, anyone who clones your project can reproduce the same software environment.

You should also be careful when upgrading packages. A major upgrade of NumPy or other core libraries might change behavior or break compatibility with a specific GATE version. Before upgrading, note the current versions and consider testing in a separate environment.

A simple strategy for beginners is:

Create one dedicated environment for GATE.
Install only what you need for the tutorials and your simulations.
When everything works, freeze the environment to requirements.txt or environment.yml.
If you want to try newer versions, create a second environment instead of modifying the working one.

Never install or upgrade packages globally on your system just to satisfy a GATE requirement. Always install into an activated virtual or conda environment, and record your package versions so your simulations remain reproducible.

2.2. Creating a Python Environment

Virtual environments

Conda environments

Managing dependencies

Comments

Where to Move