Quick Start Guide

Quick Start Guide#

This page gets you to a working PyMedPhys installation quickly.

If you are unsure which installation to choose, read Installation options first. For most users, the recommended install is:

uv python install 3.12
uv venv --python 3.12
uv pip install "pymedphys[user]"

PyMedPhys currently supports Python 3.12, 3.13, and 3.14.

Check the platform prerequisites in Installation options before choosing a different Python version.

We recommend using uv for this guide. It can install Python, create a virtual environment, and install packages with one tool.

Windows users: the commands below assume PowerShell. Linux and macOS users: the commands below assume a POSIX shell.

Install uv#

Any official uv installation method is fine. The standalone installer is shown here because it works without a pre-existing Python installation.

Windows#

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

Open a new PowerShell window if uv is not found immediately, then confirm the installation:

uv --version

Linux or macOS#

curl -LsSf https://astral.sh/uv/install.sh | sh

Open a new terminal if uv is not found immediately, then confirm the installation:

uv --version

Create a Python environment#

From the folder where you want the environment to live, run:

uv python install 3.12
uv venv --python 3.12

This creates a .venv directory in the current folder.

Install PyMedPhys#

Other installs#

For a smaller install that covers one feature, use its extra instead: gamma, dicom, mosaiq, icom, or trf. Combine them with commas, for example "pymedphys[gamma,dicom]". The optional ai extra adds the experimental AI chat app.

Because .venv exists in the current folder, uv pip install will install into that environment automatically.

Read Installation options for guidance on which combination to choose.

Use the environment#

Activate the environment so python and pymedphys resolve to the new install.

Windows#

.\.venv\Scripts\Activate.ps1

Linux or macOS#

source .venv/bin/activate

Once activated, confirm that Python can import PyMedPhys:

python -c "import pymedphys; print(pymedphys.__version__)"

Then confirm that the command line entry point is available:

pymedphys --help

To launch the graphical apps from a user installation, run:

pymedphys gui

Only this computer can connect to the apps. See Graphical apps for the available CLI options, including serving the apps to other computers.

If you plan to use command line workflows, continue to Using the CLI.

Troubleshooting installation#

TLS or certificate issues#

Some healthcare networks use a corporate trust root or HTTPS interception. In that case, tell uv to use the operating system certificate store with UV_SYSTEM_CERTS (older uv releases called this UV_NATIVE_TLS). See uv’s certificate documentation.

Windows#

$env:UV_SYSTEM_CERTS = "true"
uv pip install "pymedphys[user]"

Linux or macOS#

UV_SYSTEM_CERTS=true uv pip install "pymedphys[user]"

Proxy issues#

If your network requires an outbound proxy, define it before running uv pip install. For PyPI access, HTTPS_PROXY is the most common variable to set.

Windows#

$env:HTTPS_PROXY = "http://username:password@host:port"
uv pip install "pymedphys[user]"

Linux or macOS#

export HTTPS_PROXY="http://username:password@host:port"
uv pip install "pymedphys[user]"

Replace username, password, host, and port with the values used in your environment. If you do not know them, ask your network administrator.

Fallback if you cannot use uv#

If your workstation cannot install uv, use a standard Python virtual environment instead. This fallback assumes Python is already installed and available on PATH. If your existing installation uses py rather than python, substitute py in the commands below.

Windows#

python -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install --upgrade pip
python -m pip install "pymedphys[user]"

Linux or macOS#

python -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install "pymedphys[user]"

Next steps#