byteforce

CPN 한국어 자습서 · 외부 문서 한국어 미러

UV 문서 · Guides

Docker에서 uv 사용하기

Using uv in Docker · 원문: docs.astral.sh/uv/guides/integration/docker/

아래는 원문을 한국어로 옮긴 미러입니다. 코드·명령은 원문 그대로이며, 가장 최신 정보는 하단 원문 링크에서 확인하세요.

시작하기

uv는 바이너리 복사를 위한 distroless Docker 이미지와 인기 있는 배포판을 기반으로 하는 사전 구성된 이미지를 모두 제공합니다. Debian 컨테이너에서 uv를 실행하려면 다음 명령을 사용합니다:

코드 · 명령
docker run --rm -it ghcr.io/astral-sh/uv:debian uv --help

사용 가능한 이미지

Distroless 이미지: - ghcr.io/astral-sh/uv:latest - ghcr.io/astral-sh/uv:{major}.{minor}.{patch} (예: 0.11.24) - ghcr.io/astral-sh/uv:{major}.{minor} (최신 패치)

파생 이미지에는 uv가 사전 설치된 Alpine, Debian, Python 기반 변형이 포함됩니다.

uv 설치하기

distroless 이미지에서 바이너리를 복사합니다:

코드 · 명령
FROM python:3.12-slim-trixie
COPY --from=ghcr.io/astral-sh/uv:latest /uv /uvx /bin/

또는 설치 스크립트를 사용합니다:

코드 · 명령
FROM python:3.12-slim-trixie

RUN apt-get update && apt-get install -y --no-install-recommends curl ca-certificates
ADD https://astral.sh/uv/install.sh /uv-installer.sh
RUN sh /uv-installer.sh && rm /uv-installer.sh
ENV PATH="/root/.local/bin/:$PATH"

재현성을 위해 특정 버전을 고정하는 것을 권장합니다.

프로젝트 설치하기

코드 · 명령
COPY . /app
ENV UV_NO_DEV=1
WORKDIR /app
RUN uv sync --locked
CMD ["uv", "run", "my_app"]

중요: 빌드 시 로컬 가상환경이 포함되지 않도록 .venv를 .dockerignore에 추가하세요.

환경 사용하기

PATH를 설정하여 활성화합니다:

코드 · 명령
ENV PATH="/app/.venv/bin:$PATH"

또는 개별 명령에 uv run을 사용합니다:

코드 · 명령
RUN uv run some_script.py

설치된 도구 사용하기

코드 · 명령
ENV PATH=/root/.local/bin:$PATH
RUN uv tool install cowsay

컨테이너에서 개발하기

docker run으로 마운트하기

가상환경을 보존하면서 프로젝트를 바인드 마운트합니다:

코드 · 명령
docker run --rm --volume .:/app --volume /app/.venv [...]

Docker Compose Watch

compose.yaml에서 파일 감시를 설정합니다:

코드 · 명령
services:
  example:
    build: .
    develop:
      watch:
        - action: sync
          path: .
          target: /app
          ignore:
            - .venv/
        - action: rebuild
          path: ./pyproject.toml

docker compose watch로 실행합니다.

최적화

바이트코드 컴파일

코드 · 명령
ENV UV_COMPILE_BYTECODE=1
RUN uv sync --compile-bytecode

캐싱

더 빠른 빌드를 위해 캐시 마운트를 사용합니다:

코드 · 명령
ENV UV_LINK_MODE=copy
RUN --mount=type=cache,target=/root/.cache/uv \
    uv sync

Python 설치 캐싱을 위해 UV_PYTHON_CACHE_DIR을 설정합니다.

중간 레이어

의존성 설치와 프로젝트 코드를 분리합니다:

코드 · 명령
FROM python:3.12-slim
COPY --from=ghcr.io/astral-sh/uv:latest /uv /uvx /bin/
WORKDIR /app

RUN --mount=type=cache,target=/root/.cache/uv \
    --mount=type=bind,source=uv.lock,target=uv.lock \
    --mount=type=bind,source=pyproject.toml,target=pyproject.toml \
    uv sync --locked --no-install-project

COPY . /app
RUN --mount=type=cache,target=/root/.cache/uv \
    uv sync --locked

참고: 워크스페이스의 경우 처음에는 --frozen을 사용하고, 모든 멤버를 복사한 후 --locked를 사용합니다.

편집 불가 설치

멀티 스테이지 빌드에서 환경만 복사하려면 --no-editable을 사용합니다:

코드 · 명령
FROM python:3.12-slim AS builder
COPY --from=ghcr.io/astral-sh/uv:latest /uv /uvx /bin/
ENV UV_PYTHON_DOWNLOADS=0
WORKDIR /app

RUN --mount=type=cache,target=/root/.cache/uv \
    --mount=type=bind,source=uv.lock,target=uv.lock \
    --mount=type=bind,source=pyproject.toml,target=pyproject.toml \
    uv sync --locked --no-install-project --no-editable

COPY . /app
RUN --mount=type=cache,target=/root/.cache/uv \
    uv sync --locked --no-editable

FROM python:3.12-slim
COPY --from=builder /app/.venv /app/.venv
CMD ["/app/.venv/bin/hello"]

uv 임시 사용

최종 이미지에 포함하지 않고 uv를 마운트합니다:

코드 · 명령
RUN --mount=from=ghcr.io/astral-sh/uv,source=/uv,target=/bin/uv \
    uv sync

pip 인터페이스 사용하기

패키지 설치하기

간단하게 시스템 Python을 사용합니다:

코드 · 명령
ENV UV_SYSTEM_PYTHON=1
RUN uv pip install --system ruff

또는 가상환경을 생성합니다:

코드 · 명령
RUN uv venv /opt/venv
ENV VIRTUAL_ENV=/opt/venv
ENV PATH="/opt/venv/bin:$PATH"
RUN uv pip install ruff

요구사항 파일 설치하기

코드 · 명령
COPY requirements.txt .
RUN uv pip install -r requirements.txt

프로젝트 설치하기

코드 · 명령
COPY pyproject.toml .
RUN uv pip install -r pyproject.toml
COPY . .
RUN uv pip install -e .

이미지 출처 검증하기

GitHub CLI를 사용하여 Docker 이미지 증명을 검증합니다:

코드 · 명령
gh attestation verify --owner astral-sh oci://ghcr.io/astral-sh/uv:latest

또는 추가 검증을 위해 sigstore 인프라와 함께 cosign을 사용합니다. latest 대신 특정 버전 태그나 이미지 다이제스트를 검증하는 것이 모범 사례입니다.

원문(영어): https://docs.astral.sh/uv/guides/integration/docker/ · 본 문서는 학습용 한국어 번역이며 원본의 권리는 원저작자(Astral)에게 있습니다.

원문(영어): https://docs.astral.sh/uv/guides/integration/docker/