bump python packages, use UV instead of conda, update docker build #766

dkuegler · 2026-01-19T17:39:17Z

This PR includes:

version bumps for all python packages
removes conda environment files entirely (fastsurfer now uses UV as the default/supported package manager in both documentation and docker image)
several updates to the docker build
- UV instead of docker (significant simplification of the build)
- update to Ubuntu 24.04 as base
- update all major python packages
- add xvfb-run dependencies in the runtime to support whippersnappy (for example for CC QC images)
- add image metadata fields
- adaptations to the build script
- caching the freesurfer download instead of downloading each time is a massive speedup to the build time
- fspython is a wrapper script instead of a softlink

Todo:

~~finish surface pipeline testing~~
~~currently there is an error where Freesurfer's rca-config (a python script) cannot import yaml but yaml is installed and available in the distributed python environment~~

Copilot

Pull request overview

This PR modernizes FastSurfer's build infrastructure and dependency management by migrating from conda to UV as the package manager and updating all Python packages.

Changes:

Complete migration from conda to UV for Python environment management
Removal of all conda-specific files and configuration
Docker build refactoring to use UV instead of conda, with Ubuntu 24.04 as base
Python version references updated from python3.10 to python3 throughout scripts
Addition of xvfb-run support for headless OpenGL rendering in corpus callosum QC
Package version updates in pyproject.toml including torch 2.7.*, torchvision 0.22.1, and new dependencies

Reviewed changes

Copilot reviewed 26 out of 28 changed files in this pull request and generated 7 comments.

Show a summary per file

File	Description
tools/build/link_fs.sh	Convert string to array syntax, change error to warning
tools/build/install_fs_pruned.sh	Remove login shell, add error handling for parallel execution, convert strings to arrays
tools/Docker/install_env.py	File deleted - conda-specific environment installer
tools/Docker/build.py	Update shebang, replace conda with venv references, add new build args, update version support
tools/Docker/entrypoint.sh	Update comment from conda to venv
tools/Docker/conda_pack.sh	File deleted - conda-specific packaging script
tools/Docker/Dockerfile	Major refactor: UV instead of conda, Ubuntu 24.04, new build stages, add xvfb dependencies
tools/Docker/README.md	Update documentation for UV, new version numbers
run_fastsurfer.sh	Update python reference, add xvfb-run support for OpenGL
recon_surf scripts	Update python version references
pyproject.toml	Update dependencies, add Python 3.13 support, pin torch/torchvision versions
env/*.yml	Conda environment files deleted
doc/overview/*.md	Update documentation from conda to UV
Tutorial files	Update from conda to UV instructions
FastSurferCNN/version.py	Minor formatting changes, update git status flags
FastSurferCNN/utils/checkpoint.py	Improved error handling for checkpoint downloads
FastSurferCNN/data_loader/conform.py	Fix type annotation
CorpusCallosum/shape/mesh.py	Improve OpenGL/whippersnappy error handling

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

tools/build/install_fs_pruned.sh

tools/Docker/build.py

FastSurferCNN/utils/checkpoint.py

run_fastsurfer.sh

tools/Docker/Dockerfile

tools/build/install_fs_pruned.sh

run_fastsurfer.sh

Update pyproject dependencies. Update docker build script.

install conda pack into a separate environment add labels to the different images pass values for the labels in the images through the build script make sure linking fspython to /venv/bin/python works Some formatting cleanup Resolve upx bugs

change the virtual environment and python install command from conda to uv Remove conda-related files, as our primary install mechanism is now uv (instead of conda, with the dependencies defined in pyproject). Update version and build scripts to work with the new Dockerfile.

…king it more flexible).

Add a check/error message if we are running headless and wrap the fastsurfer-cc call in xvfb-run.

…ftlink so it uses the correct venv and search paths

… requests, so prefer b2share from juelich

…cc.py, if the QC thickness image does not get rendered (due to whippersnappy, opengl, glfw, or x-server connection/framebuffer missing.

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

Copilot

Pull request overview

Copilot reviewed 39 out of 41 changed files in this pull request and generated 11 comments.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

tools/build/fspython

Copilot · 2026-01-26T20:24:59Z

tools/Docker/build.py

-    dry_run : bool, optional
-        Whether to actually trigger the build, or just print the command to the console
-        (default: False => actually build).
+        Path o the working directory to perform the build operation (None: inherit).


Typo in comment: "o" should be "to".
The comment reads "Path o the working directory" but should read "Path to the working directory".

FastSurferCNN/download_checkpoints.py

pyproject.toml

Copilot · 2026-01-26T20:25:00Z

run_fastsurfer.sh

+      echo "WARNING: The --qc_snap option of the corpus callosum module requires OpenGL support, but we could not"
+      echo "  create OpenGL handles. For Linux headless systems, you may install xvfb-run to provide a virtual display."
+    fi
+    echo "  FastSurfer will not fail due to the inavailability of OpenGL, but some QC snapshots (rendered thickness"


Typo in error message: "inavailability" should be "unavailability".

Copilot · 2026-01-26T20:25:01Z

tools/Docker/Dockerfile

+import torch
+
+p = Path(torch.__file__).parent / "lib"
+(p / "libnvrtc.so").symlink_to(p / p.glob("libnvrtc-*.so.11.2"))


Potential bug in glob usage: The code p.glob("libnvrtc-*.so.11.2") returns a generator, but it's being passed directly to symlink_to() which expects a string or Path object. This will likely fail at runtime. The code should use next(p.glob("libnvrtc-*.so.11.2")) to get the first match from the generator, or use list(p.glob(...))[0].

Tutorial/README.md

tools/Docker/Dockerfile

tools/build/fspython

Copilot · 2026-01-26T20:25:02Z

tools/build/install_fs_pruned.sh

+  # dl aria2c if that exists, else wget or curl
+  if [[ -n "$(which aria2c)" ]] ; then dl=(aria2c -cx 16 -s 16 --check-certificate=false -o "$freesurfer_dl" "$fslink")
+  elif [[ -n "$(which wget)" ]] ; then dl=(wget --no-check-certificate -qO- "$fslink" -O "$freesurfer_dl")
+  else dl=(curl -L --insecure "$fslink" -o "$freesurfer_dl")
+  fi


The FreeSurfer archive is downloaded with TLS certificate validation explicitly disabled using aria2c --check-certificate=false, wget --no-check-certificate, or curl --insecure, and then extracted and used to provide binaries in the build/runtime image. This allows a network attacker (e.g., on the same LAN or controlling DNS) to perform a man‑in‑the‑middle attack on the download and supply a malicious FreeSurfer tarball that will be unpacked and executed during image build, compromising the build and downstream images. To mitigate this, enforce strict HTTPS certificate verification for all download methods and add an integrity check (e.g., pinned checksum or signature verification) for the FreeSurfer archive before extraction.

dkuegler force-pushed the feature/version-bump branch from c658130 to d5dadad Compare January 19, 2026 18:08

m-reuter requested a review from Copilot January 19, 2026 18:37

Copilot started reviewing on behalf of m-reuter January 19, 2026 18:37 View session

Copilot AI reviewed Jan 19, 2026

View reviewed changes

dkuegler force-pushed the feature/version-bump branch 4 times, most recently from 37e500d to d208b9e Compare January 21, 2026 18:09

m-reuter reviewed Jan 23, 2026

View reviewed changes

run_fastsurfer.sh Show resolved Hide resolved

dkuegler force-pushed the feature/version-bump branch 3 times, most recently from a68b22e to ef53e04 Compare January 23, 2026 18:16

dkuegler added 14 commits January 26, 2026 14:44

Bump the version of miniforge, python and all python packages.

5e5ba3b

Update pyproject dependencies. Update docker build script.

rename conda image parts to venv

e96949a

install conda pack into a separate environment add labels to the different images pass values for the labels in the images through the build script make sure linking fspython to /venv/bin/python works Some formatting cleanup Resolve upx bugs

Bump internal, hard-coded references from python 3.10 to python 3 (ma…

cd3093e

…king it more flexible).

Make FastSurfer compatible with numpy2

3a7576b

Update the checkpoint download to summarize and print error messages

8a3d010

Fix numpy 2 incompatibility in conform

3ba6c5d

Add whippersnappy dependencies to the Dockerfile

8dcf111

Add a check/error message if we are running headless and wrap the fastsurfer-cc call in xvfb-run.

Fix fspython in freesurfer build image to be a script instead of a so…

a01f27a

…ftlink so it uses the correct venv and search paths

download freesurfer into a cache directory for speed

fdf02c8

Fix overflow error in segstats (numpy2)

001a736

zenodo is artificially slowing down the download of files with python…

b9e6c21

… requests, so prefer b2share from juelich

Clean up, simplify, standardize and parallelize download of checkpoints

bd24770

Better detection of incompatible CUDA version

c4aaa3a

dkuegler force-pushed the feature/version-bump branch from 26066ee to c4aaa3a Compare January 26, 2026 17:04

dkuegler and others added 2 commits January 26, 2026 18:25

Warning in run_fastsurfer.sh and successful processing in fastsurfer_…

1b6c42b

…cc.py, if the QC thickness image does not get rendered (due to whippersnappy, opengl, glfw, or x-server connection/framebuffer missing.

Github copilot suggestion/comment to improve cuda11.8 docker build

9cf0609

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

dkuegler force-pushed the feature/version-bump branch from 8e1d060 to 9cf0609 Compare January 26, 2026 18:40

dkuegler marked this pull request as ready for review January 26, 2026 18:43

m-reuter requested a review from Copilot January 26, 2026 20:18

Copilot started reviewing on behalf of m-reuter January 26, 2026 20:18 View session

Copilot AI reviewed Jan 26, 2026

View reviewed changes

bump python packages, use UV instead of conda, update docker build #766

Are you sure you want to change the base?

bump python packages, use UV instead of conda, update docker build #766

Conversation

dkuegler commented Jan 19, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Copilot AI Jan 26, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Copilot AI Jan 26, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jan 26, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI Jan 26, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

dkuegler commented Jan 19, 2026 •

edited

Loading