Pixi container

Docker + Pixi Skill

Package projects into Docker containers using pixi for fast, reliable dependency management.

Workflow

Step 1: Verify Package Names

Before adding dependencies to pixi.toml, verify every package name and source. Never guess package names — always search conda-forge, bioconda, or PyPI.

For each dependency:

1. Search conda-forge: https://prefix.dev/channels/conda-forge/packages/<package-name> or pixi search <package-name>
2. Search bioconda if needed: https://prefix.dev/channels/bioconda/packages/<package-name>
3. Search PyPI: https://pypi.org/project/<package-name>/

Naming conventions:

• R packages from CRAN on conda-forge: r- prefix (e.g., r-seurat, r-ggplot2)
• R packages from Bioconductor on bioconda: bioconductor- prefix (e.g., bioconductor-deseq2)
• Python packages use their PyPI name

Step 2: Create or Update pixi.toml

Every pixi Docker build starts with a pixi.toml or pyproject.toml:

[workspace]
channels = ["conda-forge"]
platforms = ["linux-64"]

[dependencies]
python = ">=3.11"
numpy = "*"
pandas = "*"

[pypi-dependencies]
some-pypi-only-pkg = "*"

Key rules:

• Always include python version constraint
• Use [dependencies] for conda packages
• Use [pypi-dependencies] for PyPI-only packages
• Add bioconda to channels if using bioconductor packages

Step 3: Generate Lockfile and Version Report

Run locally before building:

pixi install
pixi list --explicit > env.txt

env.txt provides a human-readable summary of locked versions for sharing and reference.

Step 4: Choose Base Image

Pixi-docker provides multiple base images. Select based on CUDA requirements:

Default (no CUDA):

FROM ghcr.io/prefix-dev/pixi:latest AS build

With CUDA - Follow this process to select the appropriate image:

1. Detect CUDA version from pixi.toml:

   [system-requirements]
   cuda = "12"
   

2. Check local docker/podman cache for matching pixi CUDA image:

   docker images ghcr.io/prefix-dev/pixi | grep cuda
   # or
   podman images ghcr.io/prefix-dev/pixi | grep cuda
   

3. If found locally, use the cached image directly.

4. If not found locally, query the registry:

   • Visit https://github.com/prefix-dev/pixi-docker/pkgs/container/pixi
   • Search for tags matching CUDA version (e.g., noble-cuda-13.0.0, jammy-cuda-12.x)
   • Format: {os}-cuda-{cuda-version} or {version}-{os}-cuda-{cuda-version}

5. Pull and use the selected image.

Step 5: Create Dockerfile

Use the shell-hook multi-stage build pattern for production.

Stage 1 (Build): Contains pixi for dependency installation Stage 2 (Production): Minimal image without pixi, use slim version for smaller size

Match production stage with build stage base distro using the same version's slim variant:

• Ubuntu → ubuntu:{version}-slim (e.g., noble=24.04 → ubuntu:24.04-slim)
• Debian → debian:{codename}-sllim (e.g., bookworm → debian:bookworm-slim)

The agent should infer the correct production image from the build stage's base OS.

# Build stage
FROM ghcr.io/prefix-dev/pixi:latest AS build

WORKDIR /app

# Copy pixi manifest and lockfile first (better layer caching)
COPY pixi.toml pixi.lock ./

# Configure mirrors based on location detection
COPY configs/ /tmp/configs/
RUN if [ "$(curl -s --connect-timeout 2 https://ipinfo.io/country 2>/dev/null)" = "CN" ]; then \
    mkdir -p /root/.pixi && \
    cp /tmp/configs/tsinghua.toml /root/.pixi/config.toml; \
fi

# Install dependencies with locked versions
RUN pixi install --locked

# Create shell-hook activation script
RUN pixi shell-hook -s bash > /shell-hook.sh && \
    echo 'exec "$@"' >> /shell-hook.sh

# Production stage - use slim version for smaller size
FROM ubuntu:24.04-slim AS production

WORKDIR /app

# Copy only the environment (not pixi itself)
# Note: path must stay the same as in build stage
COPY --from=build /app/.pixi/envs/default /app/.pixi/envs/default
COPY --from=build /shell-hook.sh /shell-hook.sh
RUN chmod +x /shell-hook.sh

COPY . .

ENTRYPOINT ["/bin/bash", "/shell-hook.sh"]
CMD ["python", "main.py"]

Key patterns:

• Use multi-stage build to exclude pixi from production image
• Use --locked to ensure lockfile matches manifest
• Shell-hook creates environment activation without pixi installed
• Path must stay same (/app/.pixi/envs/default)
• Production stage uses slim image for smaller size

Step 6: Configure Mirrors (Optional)

For users in China, pre-configured mirror files are provided:

Config	Contents
configs/default.toml	No mirrors (default sources)
configs/tsinghua.toml	Tsinghua mirrors for conda and PyPI
configs/aliyun.toml	Aliyun mirrors

IP-based auto-selection:

RUN if [ "$(curl -s --connect-timeout 2 https://ipinfo.io/country 2>/dev/null)" = "CN" ]; then \
    cp /tmp/configs/tsinghua.toml /root/.pixi/config.toml; \
fi

Step 7: Build, Verify, and Clean

7.1 Detect Runtime and Determine Tag

source scripts/detect_runtime.sh

IMAGE_NAME=$(basename "$(pwd)")
TAG="$(date +%Y%m%d)-$(git rev-parse --short HEAD 2>/dev/null || echo local)"
IMAGE_TAG="${IMAGE_NAME}:${TAG}"

7.2 Build the Image

timeout 7200 $RUNTIME build $BUILD_FLAGS -t "${IMAGE_TAG}" .

7.3 Verify Installation

Run commands through the entrypoint (simulates actual usage):

# Python packages
$RUNTIME run --rm "${IMAGE_TAG}" python -c "import numpy; import pandas; print('OK')"

# R packages
$RUNTIME run --rm "${IMAGE_TAG}" R -e "library(ggplot2); cat('OK\n')"

7.4 Clean Dangling Images

$RUNTIME image prune -f

7.5 Report to User

Report:

• Image name and tag
• Key package versions (from env.txt)
• Verification result

Multi-environment Support

Pixi supports multiple environments (e.g., default, prod, test). To deploy a specific environment:

ARG ENV_NAME=default
RUN pixi install --locked -e ${ENV_NAME}
COPY --from=build /app/.pixi/envs/${ENV_NAME} /app/.pixi/envs/${ENV_NAME}
RUN pixi shell-hook -e ${ENV_NAME} -s bash > /shell-hook.sh

PyTorch / Deep Learning

For PyTorch with CUDA, use conda-forge packages:

[system-requirements]
cuda = "12"

[dependencies]
pytorch-gpu = "*"
cuda-version = "12.6.*"

Or use PyPI with custom index:

[pypi-dependencies]
torch = { version = ">=2.5.1", index = "https://download.pytorch.org/whl/cu124" }

Important: If using PyPI for PyTorch, ensure all packages depending on torch also come from PyPI.

R Projects

For R packages, use conda-forge and bioconda:

[workspace]
channels = ["conda-forge", "bioconda"]

[dependencies]
r-base = ">=4.1"
r-ggplot2 = "*"
bioconductor-deseq2 = "*"

.dockerignore

Create .dockerignore before building:

.git
__pycache__
*.pyc
.env
.pixi
*.md
tests/
docs/