Which Python does pip use?

Install a supported Python with pip first, for example using the Python downloads or your platform’s Python provider. Installing gprMax with pip does not install Python itself.

python -m pip installs into the Python selected by python; it does not install gprMax into every Python on the computer. A terminal with an activated Conda environment uses that environment’s Python, even though the installer is pip. python may be called python3 or python3.12 on your system; on Windows, py -3.12 can select an installed Python 3.12. Use the same interpreter for installation and execution.

If you are unsure which interpreter is selected, check it before installing:

$ python -c "import sys; print(sys.executable); print(sys.version)"
$ python -m pip --version

These are setup/troubleshooting checks, not commands required before each simulation. See the pip user guide for how interpreter selection works.

Option A: use a virtual environment

A venv keeps gprMax and its dependencies separate from other Python projects. With a separately installed Python 3.12, create a new working folder and environment. Do not create it inside your old v3 checkout.

Linux/macOS (bash or zsh):

$ mkdir gprmax-work
$ cd gprmax-work
$ python3.12 -m venv .venv
$ source .venv/bin/activate
$ python -m pip install gprMax
$ python -m gprMax --help

Windows (PowerShell):

mkdir gprmax-work
cd gprmax-work
py -3.12 -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install gprMax
python -m gprMax --help

In a later terminal, return to gprmax-work and activate the existing environment again; do not recreate or reinstall it for each simulation. Alternatively, activation is optional if you call its Python explicitly:

$ .venv/bin/python -m gprMax model.in

On Windows, the equivalent is .\.venv\Scripts\python.exe -m gprMax model.in. This also avoids changing PowerShell execution policy if activation scripts are blocked. Use deactivate when finished with an activated venv. See the Python venv documentation for other shells. If Conda is already active and you want a non-Conda setup, deactivate it and select your separately installed Python explicitly.

Option B: install without a virtual environment

On a user-managed Python installation that permits pip package installation, you can install and run directly, with no activation step:

$ python -m pip install gprMax
$ python -m gprMax model.in

Here model.in is your input file. This route shares dependencies with other packages in that Python installation. Updates may affect those projects, and v3 and v4 are not independently selectable installations in the same environment. If that Python already contains v3, use a separate environment to preserve it rather than installing over it.

If pip reports externally-managed-environment, the OS or another package manager owns that Python. Use Option A or a separate user-managed Python. Do not use sudo pip or --break-system-packages as a routine workaround: overriding those safeguards can interfere with software managed by the OS. --user is not an isolation mechanism and may also be blocked. See the externally managed environments guidance.

If installation fails because the destination is not writable, create a venv in a writable directory rather than elevating permissions.

Working directories and installed files

Run models and plotting commands from your own working directory. Neither a wheel installation nor its toolboxes require you to enter site-packages. Keep inputs, scripts and outputs outside the installed package so that an upgrade does not overwrite your work. See Running gprMax for a complete example and Using the installed toolboxes for toolbox commands and assets.

There is no single installation path: it depends on the selected Python. For the Linux/macOS environment above it is normally gprmax-work/.venv/lib/python3.12/site-packages/gprMax/; on Windows it is gprmax-work\.venv\Lib\site-packages\gprMax\. Locate the actual installation with:

$ python -c "import gprMax; print(gprMax.__file__)"

Do not run v4 from a directory containing an old v3 gprMax package, or add the old checkout to PYTHONPATH. A local package can shadow the installed one, even after changing environments. Select the same environment in your IDE or notebook kernel as in the terminal.

Optional features

Install only the optional features you need, into the same selected Python:

$ python -m pip install "gprMax[mpi]"
$ python -m pip install "gprMax[cuda]"
$ python -m pip install "gprMax[opencl]"
$ python -m pip install "gprMax[metal]"

These extras install Python bindings only. MPI, CUDA, OpenCL, and Metal still require compatible system runtimes and hardware as described below and in the accelerator documentation.

Keeping v3 and v4 side by side

Keep the old environment and, for an editable installation, its source checkout. Do not rename, delete or update that checkout to v4: the v3 environment may import directly from it. Use a separate checkout for v4 development and separate working/output directories for comparisons.

If the original v3 environment is named gprMax, select versions with:

$ conda activate gprMax-v4
$ python -m gprMax model_v4.in
$ conda activate gprMax
$ python -m gprMax model_v3.in

Replace gprMax with the actual old environment name. There is no machine-wide “default gprMax” that permanently wins: the selected interpreter and its import paths determine the version. Both versions use the package name gprMax. Do not install v4 or apply the v4 conda_env.yml to the old environment if you want v3 to remain available; avoid using Conda’s base environment for either project.

For a one-time coexistence check, run this outside both source checkouts:

$ python -c "import sys, gprMax; print(sys.executable); print(gprMax.__version__); print(gprMax.__file__)"

Installing v4 does not itself convert v3 inputs or results. Read the v3-to-v4 migration guide before comparing them.

1. Install a C compiler which supports OpenMP

  $ xcode-select --install
  $ brew install libomp

gprMax detects ``libomp`` from Homebrew, the active Python environment, or
``GPRMAX_LIBOMP_PREFIX``. The previous Homebrew GCC requirement is no longer
necessary.

2. [Optional] Install MPI

MPI is required only for domain decomposition and task farming. Ordinary serial, OpenMP, CUDA, OpenCL, and Metal simulations do not require an MPI runtime or the mpi4py Python package. The mpi4py binding is installed through the gprMax mpi extra in step 6.

If you plan to use MPI and are running gprMax on an HPC system, a suitable MPI implementation will likely be installed already. Otherwise you will need to install one yourself.

3. Install Python, the required Python packages, and get the gprMax source

Install Conda if it is not already available, and install Git. There is no need to replace an existing Conda installation or make its Python the system-wide default. The Python in Conda’s base environment can differ from Python 3.12 in the development environment.

The following commands select the devel branch for v4 development, not a pinned release. To build a published release instead, check out that release’s tag in the new checkout before creating its environment. Use a new directory and environment name; do not reuse your v3 checkout or environment:

$ git clone --branch devel https://github.com/gprMax/gprMax.git gprMax-v4-src
$ cd gprMax-v4-src
$ conda env create -f conda_env.yml
$ conda activate gprMax-v4

The YAML file defaults to gprMax-v4. This step installs development dependencies, not gprMax itself; step 6 builds and installs the checkout. MPI and accelerator bindings remain optional. If gprMax-v4 already exists, keep it and choose a different name with --name rather than overwriting it.

For a non-Conda source environment, create and activate a venv using the earlier instructions, then run python -m pip install -r requirements.txt from the checkout for the common development/test dependencies. Optional CAD, MPI and accelerator libraries still need their own installation instructions. For a minimal source installation, step 6 installs the declared package dependencies and isolated build requirements without that development list.

4. [Optional] Build h5py against Parallel HDF5

If you plan to use parallel HDF5 output with the MPI domain decomposition functionality available in gprMax, h5py must be built with MPI support.

$ conda install -c conda-forge "h5py>=2.9=mpi*"

$ CC=mpicc HDF5_MPI=ON python -m pip install --force-reinstall --no-deps --no-cache-dir --no-binary=h5py h5py

$ python -c "import h5py; print(h5py.get_config().mpi)"

5. [Optional] Install mpi4py_fft

If you plan to use the MPI domain decomposition functionality with fractal user objects, you need to install mpi4py_fft.

Python 3.12 is recommended for this optional configuration. mpi4py_fft contains Python-version-specific compiled extensions and also requires a compatible MPI implementation and FFTW installation, so it is more sensitive to the local software stack than the core gprMax package.

$ brew install fftw

$ conda install -c conda-forge mpi4py_fft

$ python -m pip install mpi4py_fft

6. Build and install gprMax

Stay in the top-level gprMax-v4-src checkout (the directory containing setup.py and pyproject.toml), with gprMax-v4 or your chosen source-build environment active:

$ python -m pip install -e .

The . means this checkout, and -e makes the installation editable. Python changes are read from these files; changes to compiled Cython code require rebuilding with the same command. Do not delete or move the checkout while using its editable installation. For a non-editable source install, use python -m pip install . instead.

Release and ordinary source builds use portable instruction sets. Developers making a private build for the current host can opt into machine-specific optimisation on Linux or macOS:

$ GPRMAX_BUILD_NATIVE=1 python -m pip install -e .

Do not redistribute a native build: it may contain instructions unavailable on another processor. Published binary wheels never enable this option. Two extension modules are compiled concurrently by default; constrained systems can set GPRMAX_BUILD_JOBS=1, while release builders may select a larger positive value.

For MPI domain decomposition or task farming, install the MPI extra instead:

$ python -m pip install -e ".[mpi]"

For distributed fractal generation, use the combined extra:

$ python -m pip install -e ".[mpi-fractals]"

The mpi-fractals extra includes both mpi4py and mpi4py-fft. If a core source installation is already built, MPI support can be added without recompiling gprMax by installing the system MPI runtime and then running python -m pip install mpi4py (plus mpi4py-fft for distributed fractals). A compatible system MPI runtime is still required; the Python extra does not install or configure that runtime.

Accelerator bindings are also optional and can be installed independently:

$ python -m pip install -e ".[cuda]"       # NVIDIA CUDA; Linux/Windows
$ python -m pip install -e ".[opencl]"     # OpenCL
$ python -m pip install -e ".[metal]"      # Apple Metal; macOS

These editable targets refer to the current checkout. In contrast, python -m pip install "gprMax[cuda]" selects the published distribution; do not substitute that command when you mean to use your edited source.

Several extras can be requested together, for example .[cuda,opencl]. The .[accelerators] convenience extra requests every accelerator binding applicable to the current operating system. It is not the default because package installers cannot detect whether a compatible device, driver, CUDA toolkit, or OpenCL runtime is present, and building an unavailable binding can prevent installation. The backend-specific system software described in the accelerator documentation is still required.

The interactive Marimo dashboards have their own optional dependencies:

$ python -m pip install -e ".[marimo]"

See the Marimo toolbox documentation for the available A-scan, B-scan, progress, and introductory processing dashboards.

You are now ready to proceed to running gprMax.