Installation¶

KonfAI targets Python 3.10+ and depends on PyTorch, SimpleITK, TensorBoard, and a set of medical-imaging utilities.

Install from PyPI¶

python -m pip install konfai

This installs the core CLI entrypoints:

konfai
konfai-cluster with the cluster extra

Optional extras exposed by the package metadata:

python -m pip install "konfai[cluster]"
python -m pip install "konfai[vtk]"
python -m pip install "konfai[lpips]"

These extras enable optional entrypoints or integrations:

konfai-cluster with cluster
VTK-dependent features with vtk
LPIPS-based metrics with lpips

Install the standalone apps package separately when you need packaged app execution:

python -m pip install konfai-apps

This provides:

konfai-apps
konfai-apps-server
the Python API under konfai_apps

Install from source¶

Use an editable install when you want to:

work on the framework itself
modify example YAML files
create local Python modules next to your configs
build the documentation

git clone https://github.com/vboussot/KonfAI.git
cd KonfAI
python -m pip install -e .

PyTorch and GPU notes¶

KonfAI declares torch as a dependency, but the correct GPU-enabled PyTorch wheel still depends on your platform, drivers, and CUDA setup. In practice:

if your default PyTorch install already matches your machine, pip install konfai is enough
if you need a specific CUDA or CPU-only wheel, install PyTorch first, then install KonfAI
for containerized usage, see Docker usage

Verify the installation¶

Check that the package imports correctly:

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

Check that the main CLIs are available:

konfai --help

If you installed the standalone apps package or the cluster extra:

konfai-apps --help
konfai-apps-server --help
konfai-cluster --help

For a first real run after installation, go to :doc:../quickstart.

Common installation issues¶

`ModuleNotFoundError` after installation¶

This usually means the package was installed into a different Python environment than the one you are currently using. Re-run the install with the same interpreter you will use to launch KonfAI:

python -m pip install -e .

GPU is available in Python but not in KonfAI¶

KonfAI relies on PyTorch device discovery and CUDA_VISIBLE_DEVICES. Check both:

python -c "import torch; print(torch.cuda.is_available(), torch.cuda.device_count())"
echo "$CUDA_VISIBLE_DEVICES"

`konfai-apps-server` is missing¶

Install the standalone apps package:

python -m pip install konfai-apps

`konfai-cluster` is missing¶

Install the cluster extra:

python -m pip install "konfai[cluster]"