From 38bdf25f8d34cf87f1151030ee89b012a9d85bfa Mon Sep 17 00:00:00 2001 From: Mohammad Miadh Angkad <176301910+mmangkad@users.noreply.github.com> Date: Tue, 6 Oct 2026 21:10:09 +0000 Subject: [PATCH] [Docker] Use uv-managed Python 3.12 and uv for all installs in the CUDA image (#42612) Co-authored-by: Mohammad Angkad --- docker/Dockerfile | 150 +++++++++++++++++++++++++--------------------- 1 file changed, 83 insertions(+), 67 deletions(-) diff --git a/docker/Dockerfile b/docker/Dockerfile index 8a5e2d4877..43dc0907db 100644 --- a/docker/Dockerfile +++ b/docker/Dockerfile @@ -1,4 +1,9 @@ ARG CUDA_VERSION=13.0.3 +ARG UV_VERSION=latest +ARG PYTHON_VERSION=3.12 + +FROM ghcr.io/astral-sh/uv:${UV_VERSION} AS uv + FROM nvidia/cuda:${CUDA_VERSION}-cudnn-devel-ubuntu24.04 AS base ARG TARGETARCH @@ -32,20 +37,26 @@ RUN if [ -n "$UBUNTU_MIRROR" ]; then \ sed -i "s|http://.*security.ubuntu.com|$UBUNTU_MIRROR|g" /etc/apt/sources.list; \ fi -# Python setup (combined with apt update to reduce layers) -# Ubuntu 24.04 ships Python 3.12 in main, so we no longer need the deadsnakes -# PPA. Dropping it avoids transient Launchpad 504s in `add-apt-repository`. -RUN --mount=type=cache,target=/var/cache/apt,id=base-apt \ - apt update && apt install -y --no-install-recommends wget software-properties-common \ - && apt install -y --no-install-recommends python3.12-full python3.12-dev \ - && update-alternatives --install /usr/bin/python3 python3 /usr/bin/python3.12 2 \ - && update-alternatives --set python3 /usr/bin/python3.12 \ - # Fix for apt-add-repository - && cd /usr/lib/python3/dist-packages/ \ - && ln -s apt_pkg.cpython-312-*-linux-gnu.so apt_pkg.so - # create virtual env for sglang to avoid conflict with system python packages -RUN python3 -m venv /opt/sglang +ARG PYTHON_VERSION +COPY --from=uv /uv /uvx /usr/local/bin/ +ENV UV_PYTHON_INSTALL_DIR=/opt/python \ + UV_PYTHON_PREFERENCE=only-managed \ + UV_LINK_MODE=copy \ + VIRTUAL_ENV=/opt/sglang +RUN --mount=type=cache,target=/root/.cache/uv \ + if [ -n "${PIP_DEFAULT_INDEX}" ]; then \ + mkdir -p /etc/uv \ + && printf '[[index]]\nurl = "%s"\ndefault = true\n' "${PIP_DEFAULT_INDEX}" > /etc/uv/uv.toml; \ + fi \ + && if [ "${GITHUB_ARTIFACTORY}" != "github.com" ]; then \ + export UV_PYTHON_INSTALL_MIRROR="https://${GITHUB_ARTIFACTORY}/astral-sh/python-build-standalone/releases/download"; \ + fi \ + && uv --version \ + && uv python install ${PYTHON_VERSION} \ + && uv venv --seed --python ${PYTHON_VERSION} /opt/sglang \ + && uv pip install --upgrade pip \ + && /opt/sglang/bin/python -VV ENV PATH="/opt/sglang/bin:${PATH}" # Install system dependencies (organized by category for better caching) @@ -53,7 +64,6 @@ RUN --mount=type=cache,target=/var/cache/apt,id=base-apt \ apt-get update && apt-get install -y --no-install-recommends \ # Core system utilities ca-certificates \ - software-properties-common \ netcat-openbsd \ kmod \ unzip \ @@ -115,7 +125,9 @@ RUN --mount=type=cache,target=/var/cache/apt,id=base-apt \ check \ libsubunit0 \ libsubunit-dev \ - && ln -sf /usr/bin/python3.12 /usr/bin/python \ + && rm -f /usr/bin/python \ + && printf '#!/bin/sh\nexec /opt/sglang/bin/python "$@"\n' > /usr/bin/python \ + && chmod +x /usr/bin/python \ && rm -rf /var/lib/apt/lists/* \ && apt-get clean @@ -181,17 +193,17 @@ RUN curl --proto '=https' --tlsv1.2 --retry 3 --retry-delay 2 -sSf https://sh.ru && rustc --version && cargo --version # Install sgl-kernel (from pre-built wheel) -RUN --mount=type=cache,target=/root/.cache/pip \ - python3 -m pip install --upgrade pip setuptools wheel html5lib six \ +RUN --mount=type=cache,target=/root/.cache/uv \ + uv pip install --upgrade pip setuptools wheel html5lib six \ && case "$CUDA_VERSION" in \ 13.0.3) ;; \ *) echo "Unsupported CUDA version: $CUDA_VERSION" && exit 1 ;; \ esac \ - # --no-deps prevents pip from pulling torch from default PyPI - && python3 -m pip install sglang-kernel==${SGL_KERNEL_VERSION} --force-reinstall --no-deps + # --no-deps prevents uv from pulling torch from default PyPI + && uv pip install sglang-kernel==${SGL_KERNEL_VERSION} --reinstall --no-deps # Copy the dependency spec, Rust extension sources, and shared protocol crate. -# Split from the pip install so changes to these build inputs invalidate the +# Split from the dependency install so changes to these build inputs invalidate the # dependency layer, while unrelated Python source changes do not. COPY python/pyproject.toml /tmp/sglang_deps/python/pyproject.toml COPY rust/sglang-grpc /tmp/sglang_deps/rust/sglang-grpc @@ -200,7 +212,7 @@ COPY proto /tmp/sglang_deps/proto # Install sglang dependencies (torch, transformers, etc.). # Generate constraints.txt to prevent reinstalling these deps in later stages. -RUN --mount=type=cache,target=/root/.cache/pip \ +RUN --mount=type=cache,target=/root/.cache/uv \ --mount=type=cache,target=/root/.cargo/registry \ case "$CUDA_VERSION" in \ 13.0.3) CUINDEX=130 ;; \ @@ -212,14 +224,11 @@ RUN --mount=type=cache,target=/root/.cache/pip \ && echo '__version__ = "0.0.0"' > sglang/version.py \ && touch README.md \ && touch LICENSE \ - && python3 -m pip install --extra-index-url https://download.pytorch.org/whl/cu${CUINDEX} ".[${BUILD_TYPE}]" \ + && uv pip install --extra-index-url https://download.pytorch.org/whl/cu${CUINDEX} \ + --index-strategy unsafe-best-match ".[${BUILD_TYPE}]" \ && cd /sgl-workspace \ && rm -rf /tmp/sglang_deps \ - && pip freeze | grep -v "^sglang==" > /sgl-workspace/constraints.txt - -# distro resolves to the apt python3-distro under /usr/lib/python3, which the runtime -# stage does not COPY; force a pip copy into /usr/local so it survives the stage split. -RUN python3 -m pip install --ignore-installed --no-deps distro + && uv pip freeze | grep -vE "^sglang( |==|@)" > /sgl-workspace/constraints.txt # Cosmos3 guardrails default ON: sglang enables them whenever `cosmos_guardrail` # is importable (Cosmos3Pipeline.create_pipeline_stages); opt out at runtime with @@ -229,11 +238,11 @@ RUN python3 -m pip install --ignore-installed --no-deps distro # by retinaface-py — would shadow our opencv-python-headless cv2). The deps not # already in the image are installed explicitly; the find_spec check mirrors # sglang's availability probe plus cosmos_guardrail's own imports. -RUN --mount=type=cache,target=/root/.cache/pip \ - python3 -m pip install --no-deps \ +RUN --mount=type=cache,target=/root/.cache/uv \ + uv pip install --no-deps \ cosmos-guardrail==0.3.1 \ retinaface-py==0.0.2 \ - && python3 -m pip install \ + && uv pip install \ "better-profanity==0.7.0" \ "nltk==3.9.1" \ "peft==0.18.1" \ @@ -254,8 +263,7 @@ WORKDIR /build # The kernels target Hopper (sm90a) only, so skip non-x86_64 images. # setup.py derives the version from `git rev-parse`, so keep the .git dir # (a source zip archive would not build). -RUN --mount=type=cache,target=/root/.cache/pip \ - mkdir -p /wheels && \ +RUN mkdir -p /wheels && \ if [ "$(uname -m)" = "x86_64" ]; then \ git clone https://github.com/Tencent/hpc-ops.git && \ cd hpc-ops && \ @@ -273,18 +281,18 @@ ARG INSTALL_FLASHINFER_JIT_CACHE ARG FLASHINFER_VERSION # Stage jit-cache/cubin artifacts into /flashinfer_jit_output for clean COPY later -RUN --mount=type=cache,target=/root/.cache/pip \ +RUN --mount=type=cache,target=/root/.cache/uv \ case "$CUDA_VERSION" in \ 13.0.3) CUINDEX=130 ;; \ *) echo "Unsupported CUDA version: $CUDA_VERSION" && exit 1 ;; \ esac \ && mkdir -p /flashinfer_jit_output \ # flashinfer-cubin is CUDA-version-agnostic, unlike jit-cache, so its index-url has no cu${CUINDEX} suffix - && python3 -m pip install flashinfer-cubin==${FLASHINFER_VERSION} --index-url https://flashinfer.ai/whl \ + && uv pip install flashinfer-cubin==${FLASHINFER_VERSION} --index-url https://flashinfer.ai/whl \ && cp -r /opt/sglang/lib/python3.12/site-packages/flashinfer_cubin /flashinfer_jit_output/ \ && cp -r /opt/sglang/lib/python3.12/site-packages/flashinfer_cubin-*.dist-info /flashinfer_jit_output/ \ && if [ "$INSTALL_FLASHINFER_JIT_CACHE" = "1" ]; then \ - python3 -m pip install flashinfer-jit-cache==${FLASHINFER_VERSION} --index-url https://flashinfer.ai/whl/cu${CUINDEX} \ + uv pip install flashinfer-jit-cache==${FLASHINFER_VERSION} --index-url https://flashinfer.ai/whl/cu${CUINDEX} \ && cp -r /opt/sglang/lib/python3.12/site-packages/flashinfer_jit_cache /flashinfer_jit_output/ \ && cp -r /opt/sglang/lib/python3.12/site-packages/flashinfer_jit_cache*.dist-info /flashinfer_jit_output/ ; \ fi @@ -357,10 +365,10 @@ WORKDIR /build COPY sgl-model-gateway /build/sgl-model-gateway # Install Rust, build gateway binary and Python bindings, then clean up Rust toolchain -RUN --mount=type=cache,target=/root/.cache/pip \ +RUN --mount=type=cache,target=/root/.cache/uv \ curl --proto '=https' --tlsv1.2 --retry 3 --retry-delay 2 -sSf https://sh.rustup.rs | sh -s -- -y \ && export PATH="/root/.cargo/bin:${PATH}" \ - && python3 -m pip install maturin \ + && uv pip install maturin \ && cd /build/sgl-model-gateway/bindings/python \ && ulimit -n 65536 && maturin build --release --features vendored-openssl --out /build/gateway_wheels \ && cd /build/sgl-model-gateway \ @@ -396,9 +404,9 @@ WORKDIR /sgl-workspace # Copy HPC-Ops wheel and install (empty on non-x86_64; kernels are sm90a-only) COPY --from=hpc_ops_builder /wheels /tmp/wheels/hpc-ops -RUN --mount=type=cache,target=/root/.cache/pip \ +RUN --mount=type=cache,target=/root/.cache/uv \ if ls /tmp/wheels/hpc-ops/*.whl >/dev/null 2>&1; then \ - pip install --no-deps /tmp/wheels/hpc-ops/*.whl; \ + uv pip install --no-deps /tmp/wheels/hpc-ops/*.whl; \ fi && rm -rf /tmp/wheels/hpc-ops # Copy flashinfer cubin (always) and jit-cache (if installed) packages @@ -460,16 +468,16 @@ RUN --mount=type=cache,target=/var/cache/apt,id=framework-apt \ # ============================================================================= # Install Mooncake -RUN --mount=type=cache,target=/root/.cache/pip \ - python3 -m pip install mooncake-transfer-engine-cuda13==${MOONCAKE_VERSION} +RUN --mount=type=cache,target=/root/.cache/uv \ + uv pip install mooncake-transfer-engine-cuda13==${MOONCAKE_VERSION} -# Install MSCCL++ Python dependencies and package (builds extension via CMake through pip) -RUN --mount=type=cache,target=/root/.cache/pip \ +# Install MSCCL++ Python dependencies and package (builds extension via CMake through uv) +RUN --mount=type=cache,target=/root/.cache/uv \ git clone --depth=1 --branch ${MSCCLPP_VERSION} https://${GITHUB_ARTIFACTORY}/microsoft/mscclpp.git /tmp/mscclpp \ && case "${CUDA_VERSION}" in \ 13.*) \ CMAKE_ARGS="-DMSCCLPP_BYPASS_GPU_CHECK=ON -DMSCCLPP_USE_CUDA=ON -DMSCCLPP_GPU_ARCHS=80,90,100,100a,103,103a" \ - python3 -m pip install "/tmp/mscclpp[cuda13]"; \ + uv pip install "/tmp/mscclpp[cuda13]"; \ ;; \ *) \ echo "Unsupported CUDA version for MSCCL++: ${CUDA_VERSION}" && exit 1; \ @@ -478,15 +486,14 @@ RUN --mount=type=cache,target=/root/.cache/pip \ && rm -rf /tmp/mscclpp # Install essential Python packages (use constraints to prevent conflicts) -RUN --mount=type=cache,target=/root/.cache/pip \ - python3 -m pip install -c /sgl-workspace/constraints.txt \ +RUN --mount=type=cache,target=/root/.cache/uv \ + uv pip install -c /sgl-workspace/constraints.txt \ datamodel_code_generator \ pre-commit \ pytest \ black \ isort \ icdiff \ - uv \ wheel \ scikit-build-core \ py-spy \ @@ -500,20 +507,21 @@ RUN --mount=type=cache,target=/root/.cache/pip \ # DeepEP needs SGL_NCCL_VERSION at runtime even if torch pins another version; # install it after the constrained dependency solve so the solve cannot revert it. -RUN --mount=type=cache,target=/root/.cache/pip \ - python3 -m pip install --force-reinstall --no-deps \ +RUN --mount=type=cache,target=/root/.cache/uv \ + uv pip install --reinstall --no-deps \ "nvidia-nccl-cu13==${SGL_NCCL_VERSION}" # The `nixl` stub package is needed (it owns the `nixl` import path) but # unconditionally requires nixl-cu12, so install it with --no-deps and pair it # with the nixl-cu13 binary to avoid shipping wrong-CUDA libs. -RUN --mount=type=cache,target=/root/.cache/pip \ - python3 -m pip install nixl nixl-cu13 --no-deps \ - && python3 -m pip install "cuda-python>=13,<14" +RUN --mount=type=cache,target=/root/.cache/uv \ + uv pip install nixl nixl-cu13 --no-deps \ + && uv pip install "cuda-python>=13,<14" # Install the latest available AI Dynamo prerelease from NVIDIA's package index. -RUN --mount=type=cache,target=/root/.cache/pip \ - python3 -m pip install --pre --extra-index-url https://pypi.nvidia.com/ ai-dynamo +RUN --mount=type=cache,target=/root/.cache/uv \ + uv pip install --prerelease=allow --index-strategy unsafe-best-match \ + --extra-index-url https://pypi.nvidia.com/ ai-dynamo # Add yank script COPY --chown=root:root --chmod=755 docker/configs/yank /usr/local/bin/yank @@ -534,7 +542,8 @@ COPY docker/configs/.zshrc /root/.zshrc # libsqlite3-0: CVE-2025-{6965,7709} # libtasn1-6: CVE-2025-13151 # dpkg: CVE-2025-6297 -RUN python3 -m pip install --upgrade "urllib3>=2.6.3" "pillow>=12.1.1" +RUN --mount=type=cache,target=/root/.cache/uv \ + uv pip install --upgrade "urllib3>=2.6.3" "pillow>=12.1.1" RUN --mount=type=cache,target=/var/cache/apt,id=framework-apt \ apt-get update && apt-get install -y --only-upgrade \ binutils binutils-common binutils-x86-64-linux-gnu libbinutils \ @@ -577,9 +586,9 @@ RUN if [ "$BRANCH_TYPE" = "local" ]; then \ # Editable install (fast - dependencies already installed via constraints) # Clean up __pycache__/tests/pyc in same RUN to avoid writing ~28k files to layer -RUN --mount=type=cache,target=/root/.cache/pip \ +RUN --mount=type=cache,target=/root/.cache/uv \ cd /sgl-workspace/sglang \ - && python3 -m pip install --no-deps -e "python[${BUILD_TYPE}]" \ + && uv pip install --no-deps -e "python[${BUILD_TYPE}]" \ && kernels lock python \ && ( success=0; \ # aarch64: kernels-community/sgl-flash-attn3 ships no arm variants; JIT-compile at runtime. @@ -613,8 +622,8 @@ ENV SGLANG_RUST_BUILD_MODE=never # Install pre-built gateway artifacts from parallel builder COPY --from=gateway_builder /build/sgl-model-gateway-bin /opt/sglang/bin/sgl-model-gateway COPY --from=gateway_builder /build/gateway_wheels /tmp/gateway_wheels -RUN --mount=type=cache,target=/root/.cache/pip \ - python3 -m pip install --force-reinstall /tmp/gateway_wheels/*.whl \ +RUN --mount=type=cache,target=/root/.cache/uv \ + uv pip install --reinstall /tmp/gateway_wheels/*.whl \ && rm -rf /tmp/gateway_wheels # Set workspace directory @@ -658,6 +667,7 @@ FROM nvidia/cuda:${CUDA_VERSION}-cudnn-devel-ubuntu24.04 AS runtime ARG CUDA_VERSION ARG TARGETARCH ARG GDRCOPY_VERSION=2.5.1 +ARG PYTHON_VERSION ENV DEBIAN_FRONTEND=noninteractive \ CUDA_HOME=/usr/local/cuda \ @@ -669,12 +679,8 @@ ENV PATH="${PATH}:/usr/local/nvidia/bin:/usr/local/cuda/bin:/usr/local/cuda/nvvm LD_LIBRARY_PATH="${LD_LIBRARY_PATH}:/usr/local/nvidia/lib:/usr/local/nvidia/lib64" # Install runtime dependencies (devel base provides gcc/g++/build tools) -# Python 3.12 ships in Ubuntu 24.04 main, so no deadsnakes PPA needed. RUN --mount=type=cache,target=/var/cache/apt,id=runtime-apt \ apt-get update && apt-get install -y --no-install-recommends --allow-change-held-packages \ - # Python runtime - python3.12-full \ - python3.12-dev \ wget \ # Core system utilities ca-certificates \ @@ -715,14 +721,23 @@ RUN --mount=type=cache,target=/var/cache/apt,id=runtime-apt \ # GPG key verification gnupg2 \ linux-libc-dev \ - && update-alternatives --install /usr/bin/python3 python3 /usr/bin/python3.12 2 \ - && update-alternatives --set python3 /usr/bin/python3.12 \ - && ln -sf /usr/bin/python3.12 /usr/bin/python \ + && for py in python python3; do \ + rm -f /usr/bin/$py \ + && printf '#!/bin/sh\nexec /opt/sglang/bin/python "$@"\n' > /usr/bin/$py \ + && chmod +x /usr/bin/$py; \ + done \ && rm -rf /var/lib/apt/lists/* \ && apt-get clean # create virtual env for sglang to avoid conflict with system python packages -RUN python3 -m venv /opt/sglang +COPY --from=uv /uv /uvx /usr/local/bin/ +COPY --from=base /opt/python /opt/python +ENV UV_PYTHON_INSTALL_DIR=/opt/python \ + UV_PYTHON_PREFERENCE=only-managed \ + UV_LINK_MODE=copy \ + VIRTUAL_ENV=/opt/sglang +RUN UV_PYTHON_DOWNLOADS=never uv venv --python ${PYTHON_VERSION} /opt/sglang \ + && /opt/sglang/bin/python -VV ENV PATH="/opt/sglang/bin:${PATH}" # Set up locale @@ -747,6 +762,7 @@ RUN --mount=type=cache,target=/var/cache/apt,id=runtime-apt \ # Copy Python site-packages from framework (already cleaned of __pycache__/tests/pyc files) COPY --from=framework_final /opt/sglang/lib/python3.12/site-packages /opt/sglang/lib/python3.12/site-packages +COPY --from=framework_final /opt/sglang/bin/pip* /opt/sglang/bin/ # Copy SGLang workspace COPY --from=framework_final /sgl-workspace /sgl-workspace