Run with Docker¶

The repository ships a Dockerfile that builds a ready-to-run environment for the tutorial notebooks and the benchmark_examples/ scripts — no local Python, uv, or dependency setup required. It uses CPU-only PyTorch by default.

Prerequisites¶

Docker installed and running.
A checkout of the repository (the image builds from local source, so no GitHub token is needed):
```
git clone https://github.com/instadeepai/alf.git
cd alf
```

Build the image¶

docker build -t alf .

This installs the alf_core, alf_tools, and alf_tutorials packages along with the tutorials and benchmark dependency groups (JupyterLab, matplotlib, umap, ESM-2). The first build downloads PyTorch and other large wheels, so expect it to take a few minutes.

Run the tutorials¶

Launch JupyterLab and open the notebooks in your browser:

docker run --rm -p 8888:8888 alf

Then visit http://localhost:8888. The server starts in /app/tutorials, so the notebooks listed in the Tutorials are ready to open.

Note

Token authentication is disabled for convenience, so anyone who can reach port 8888 can run code in the container. Only use this on a trusted, local machine — do not publish the port to an untrusted network.

To keep edited notebooks and outputs on your host, mount the tutorials directory:

docker run --rm -p 8888:8888 -v "$(pwd)/tutorials:/app/tutorials" alf

Run the benchmark examples¶

Override the default command to run a benchmark script instead. --no-sync reuses the environment baked into the image:

docker run --rm alf uv run --no-sync \
    python benchmark_examples/benchmarking_surrogates.py \
    --dataset gfp --num-rounds 5 --batch-size 50 --num-seeds 3

The scripts write a comparison PNG and summary.csv under benchmark_examples/outputs/<script>/ inside the container. Mount that directory to keep the results on your host:

docker run --rm -v "$(pwd)/benchmark_examples/outputs:/app/benchmark_examples/outputs" \
    alf uv run --no-sync \
    python benchmark_examples/benchmarking_acquisition_functions.py --dataset gfp

See the benchmark examples README for the full list of flags.

GPU support¶

The image installs the CPU build of PyTorch. To use a GPU, run the container with the NVIDIA Container Toolkit and install the CUDA build of torch on top:

docker run --rm --gpus all -p 8888:8888 alf bash -c \
    "uv pip install torch --index-url https://download.pytorch.org/whl/cu128 && \
     uv run --no-sync jupyter lab --ip=0.0.0.0 --allow-root --IdentityProvider.token="

For a persistent GPU image, edit the torch source index in tools/pyproject.toml to pytorch-gpu before building (see the GPU Support section of the Installation Guide).