Skip to content

Installation Guide

CCCPM runs on macOS, Linux, and Windows with Python 3.10–3.14. It uses PyTorch for computation and works on CPU out of the box; GPU (CUDA) and Apple Silicon (MPS) acceleration are used automatically when available.

Quick install

Bash
pip install cccpm

We strongly recommend installing into a clean virtual environment:

Bash
python -m venv .venv
# macOS / Linux:
source .venv/bin/activate
# Windows (PowerShell):
.venv\Scripts\Activate.ps1

pip install cccpm
Bash
conda create -n cccpm python=3.11
conda activate cccpm
pip install cccpm

Verify the installation:

Bash
python -c "import cccpm; print(cccpm.__version__)"

Requirements

  • Python: 3.10, 3.11, 3.12, 3.13, or 3.14.
  • PyTorch: installed automatically as a dependency. By default you get the build appropriate for your platform (CPU on Windows, CPU/CUDA on Linux, CPU/MPS on macOS).

CPU vs GPU

You do not need a GPU — CCCPM is fast on CPU for typical connectome sizes.

  • NVIDIA GPU: pass device="cuda" to CPMAnalysis. On Linux the default wheel already includes CUDA. On Windows the default wheel is CPU-only, so install a CUDA build of PyTorch first, then CCCPM — pip keeps the torch that is already there. The same applies on Linux if the default build doesn't match your driver. Pick the CUDA version for your driver from the official PyTorch instructions, e.g.:

    Bash
    pip install torch --index-url https://download.pytorch.org/whl/cu126
pip install cccpm

  • Apple Silicon (M-series Macs): PyTorch's MPS backend is available automatically.

  • CPU only: the default — nothing extra to do. On Linux, a CPU-only torch is a much smaller download:

    Bash
    pip install torch --index-url https://download.pytorch.org/whl/cpu
pip install cccpm

Check what you got with python -c "import torch; print(torch.__version__, torch.cuda.is_available())".

Platform notes

  • On Apple Silicon (M1/M2/M3/…), make sure you are using a native arm64 Python. Modern PyTorch no longer ships x86_64 macOS wheels, so an Intel/Rosetta Python will fail to install torch (you'll see "no matching distribution" or skipped wheels). Check with:
Bash
python -c "import platform; print(platform.machine())"   # should print 'arm64'

If it prints x86_64, install a native arm64 Python (e.g. via Homebrew: brew install python@3.11) and recreate your virtual environment with it.

  • The default torch wheel includes CUDA support and is large. For a smaller, CPU-only install, see CPU vs GPU above.
  • Use a recent 64-bit Python from python.org or the Microsoft Store. Installing into a virtual environment (above) avoids most permission and PATH issues.
  • The default torch wheel is CPU-only. For an NVIDIA GPU, install a CUDA build first — see CPU vs GPU above.

Development install

To work on CCCPM itself (or use the latest unreleased changes), install from source with Poetry:

Bash
git clone https://github.com/wwu-mmll/confound_corrected_cpm.git
cd confound_corrected_cpm
poetry install            # add --with docs to build the documentation
poetry run pytest         # run the test suite

Troubleshooting

  • ModuleNotFoundError: No module named 'torch' after install — your environment couldn't install PyTorch (most often the Apple Silicon / Rosetta issue above, or an unsupported Python version). Confirm python --version is 3.10–3.14 and, on macOS, that platform.machine() is arm64.
  • pip install cccpm resolves very slowly or fails on dependency versions — make sure pip is up to date (python -m pip install --upgrade pip) and that you are on a supported Python version.
  • CUDA out of memory / wrong CUDA version — first make sure you installed the PyTorch build matching your driver (the official instructions). If the run itself runs out of VRAM, the GPU memory needed scales with the parcellation size (quadratically in the number of regions) and the amount of parallel work (number of permutations). To fit a large analysis on a limited GPU:
    • Run on CPU (CPMAnalysis(..., device="cpu")). CCCPM is fast on CPU for typical sizes; the GPU mainly helps with large permutation counts, and CPU RAM is usually far larger than VRAM.
    • Lower n_permutations — it is a linear factor on the peak memory.
    • Use a coarser atlas — memory grows with the square of the region count.
    • Set PYTORCH_CUDA_ALLOC_CONF=expandable_segments:True to reduce fragmentation (this only helps when free VRAM is fragmented, not when a single allocation is genuinely too large).

  • _tkinter.TclError: Can't find a usable tk.tcl (or init.tcl) when running an analysis or generating the report — this is a plotting error, usually on Windows. CCCPM saves all figures to disk, but matplotlib defaults to an interactive GUI backend (Tk), and some Python installs ship without a working Tcl/Tk. The simplest fix is to tell matplotlib to use the non-interactive Agg backend, which needs no GUI:

    PowerShell
    $env:MPLBACKEND = "Agg"
python your_script.py
    Batchfile
    set MPLBACKEND=Agg
python your_script.py
    Python
    import matplotlib
matplotlib.use("Agg")   # before importing cccpm or matplotlib.pyplot
import cccpm

    Alternatively, reinstall Python from python.org and make sure the "tcl/tk and IDLE" component is selected in the installer, which provides a working Tk.