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.10, 3.11, and 3.12.

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 common installs#

If you need a narrower install, here are some common patterns:

uv pip install "pymedphys[dicom,cli]"
uv pip install "pymedphys[mosaiq,cli]"
uv pip install "pymedphys[user,icom]"

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

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

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, try telling uv to use the operating system certificate store.

Windows#

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

Linux or macOS#

UV_NATIVE_TLS=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
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#

Contents