1  Install cuPhoton

1.1 Clone the repository

git clone https://github.com/NVIDIA/cuPhoton.git
cd cuPhoton

This clones the development branch, which this guide describes. To use a published version instead, pick its tag from Releases, add --branch TAG to the clone command, and use the documentation in that checkout.

1.2 Choose a profile

A profile selects optional dependencies through extras. The CPU command also selects the docs dependency group used to build this guide. Choose one command:

# CPU examples: CPU PyTorch, Matplotlib, Jupyter, xImage and catalog tables
uv sync --locked --python 3.12 --group docs --extra ximage --extra catalog

# NVIDIA GPU with CUDA 13: adds the GPU readers and CUDA PyTorch
uv sync --locked --python 3.12 --extra gpu --extra ximage --extra catalog

Add an extra for each optional workflow:

The docs group includes Matplotlib for the figures and CPU-only PyTorch. It cannot be combined with the gpu extra. With the GPU command, add Matplotlib after syncing with uv pip install matplotlib. Selecting torch or ximage without the docs group uses the default PyTorch distribution, which can install CUDA runtime packages on Linux even if you intend to run on the CPU.

List every extra and dependency group you want in one uv sync call. A later call without one removes its otherwise-unused dependencies. uv sync also removes packages you added with uv pip install, such as the transient-chain example (Chapter 9). Reinstall them after each sync. Use uv run --no-sync for the commands below, or activate the environment with source .venv/bin/activate before running the other chapters’ plain python and cuphoton commands.

To install into an existing environment with pip instead, run python -m pip install -e '.[ximage,catalog]' matplotlib from the checkout. This resolves dependencies independently of uv.lock and does not select the docs group’s CPU-only PyTorch index. The supported platform and lock file are Linux; this guide does not validate a macOS installation.

The native GPU FITS reader (xDR) needs a separate source build even with the gpu profile. Refer to the xDR install notes. Without it, cuPhoton reads FITS files with Astropy.

The native backends of xRep, xPois and xFit (Chapter 3), and xDR’s native pixel restoration (Chapter 4), need CUDA runtime dependencies and compiled extensions. Setting CUPHOTON_XFIT_BUILD_EXT=1 during a source build enables xFit and, by default, the shared imaging extension; CUPHOTON_IMAGING_BUILD_EXT=1 can build the imaging extension independently. The combined build needs Linux, a CUDA 13 toolkit with cuBLAS, cuSOLVER and cuFFT, a C++17 compiler, and matching CCCL headers. Refer to the native xFit build notes. Building these extensions does not build xDR’s separate FITS reader.

1.3 Check the installation

Run these from the checkout:

uv run --no-sync python -c "import cuphoton; print(cuphoton.__version__)"
uv run --no-sync cuphoton --help

The first command prints the version. The second lists the command groups, one per module:

cuphoton

GPU-accelerated astronomy and imaging tools.

Available groups:
  xdr  xDataReader: GPU-native FITS loading.
  xfit  xFit: Batched nonlinear least-squares fitting for astronomical models.
  ximage  Multi-frame image reconstruction and PSF calibration.
  xpois  Optimal image subtraction for astronomical images.
  xscan  Transient-candidate dataset, training, and review workflows.
  xrep  xRep (xReproject): WCS-aware astronomical image reprojection and stacking.
  xray  GPU-accelerated X-ray detector analysis tools.
  xlens  cuPhoton xLens: scientific monitoring and evidence review.
  xbeam  xBeam: Time-series correlation and VLBI visibility generation.

Use 'cuphoton GROUP --help' for group help.

To exercise xFit, xPois, xScan, xRep and xRay on small generated inputs, run the repository’s smoke test. Each run needs a new output directory:

uv run --no-sync python examples/run_quickstarts.py --profile cpu --output-dir /tmp/cuphoton-quickstart

With the GPU environment, replace --profile cpu with --require-gpu to require GPU execution:

uv run --no-sync python examples/run_quickstarts.py --require-gpu --output-dir /tmp/cuphoton-gpu-quickstart

The flags --profile cpu and --require-gpu are incompatible. The run writes a summary.json that names the backend and device each selected component used. It does not test every module or establish that the native xDR reader is available.

1.4 Next steps

Run Chapter 2, a five-minute tutorial that finds what changed between two images.