검색을 하다가 우연히 python의 uv 사용법를 보면서 파이썬 상태관리 도구로써 uv 패키지가 있다는 내용을 알게 되었습니다. 2024-02-16 에 처음 릴리즈된 도구임에도 2025-04-21 현재 50,617 개의 별을 받을 정도로 시간대비 상당히 높은 관심을 받고 있다는 것을 확인할 수 있었습니다.

Rust를 활용한 polars 의 효과를 확인했던 경험이 있었기 때문에, 기능에 대한 의심은 없었고 바로 적용해본 결과 상당히 효과적인 내용을 바로 확인할 수 있었습니다. 또한 Django 를 배포할 때에도 uv/Using uv in Docker 와 Reddit/django 내용을 참고하여 Dockerfile 에서 적용 가능하는 것을 확인 할 수 있습니다.

FROM python:3.12-slim-bookworm

# The installer requires curl (and certificates) to download the release archive
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

# Copy the project into the image
WORKDIR /usr/src/app

# Ensure the installed binary is on the `PATH`
ENV PATH="/root/.local/bin/:$PATH"
COPY --from=ghcr.io/astral-sh/uv:0.4.12 /uv /bin/uv

# Copy the local package or dependencies (adjust path accordingly)
RUN uv venv
ENV PATH="/app/.venv/bin:$PATH"
COPY requirements.txt /app/requirements.txt
RUN uv pip install --no-cache-dir -r ./requirements.txt
WORKDIR ./django

CMD ["uv", "run", "gunicorn", "--bind", "0.0.0.0:8000", "server.wsgi:application"]
CMD ["uv", "server.asgi:application"]
EXPOSE 8000


UV

Install

uv/Installation 공식 홈페이지의 설치방법을 그대로 적용 합니다.

$ curl -LsSf https://astral.sh/uv/install.sh | sh

Python Venv

최대장점은 docker 와 동일하게 파이썬 언어가 localhost 에 설치되어 있지 않더라도 다양한 버젼을 설치 및 활용할 수 있다는 장점이 있습니다.

# Timezone 설정
ln -sf /usr/share/zoneinfo/Asia/Seoul /etc/localtime

# 의존성 패키지 설치
apt update && apt install -y vim curl fuse libfuse2
apt-get install -y pkg-config default-libmysqlclient-dev build-essential python3-dev
apt-get install -y mariadb-client

# uv 설치하기 & C 활성화
curl -LsSf https://astral.sh/uv/install.sh | sh
source $HOME/.local/bin/env
export CC=gcc

# NeoVim 설치하기 (Optional)
apt install -y software-properties-common && add-apt-repository -y ppa:neovim-ppa/stable && apt update && apt install -y neovim

Ubuntu 컨테이너 내부에서 uv 활용하기

$ uv init -p 3.13                           
Initialized project `test`

$ uv add django                             
Using CPython 3.13.3
Creating virtual environment at: .venv
Resolved 5 packages in 3ms
Installed 3 packages in 82ms
 + asgiref==3.8.1
 + django==5.2
 + sqlparse==0.5.3

명령어

  • uv init : 새로운 파이썬 프로젝트를 생성 (pyproject.toml 파일을 생성)
  • uv add : 프로젝트의 종속성을 추가 (pip install)
  • uv remove : 프로젝트의 종속성을 삭제함 (pip uninstall)
  • uv sync : 프로젝트의 종속성을 환경과 동기화함
  • uv lock : 프로젝트의 종속성에 대한 잠금 파일을 생성함
  • uv run : 프로젝트 환경에서 명령어를 실행함 (python ./main.py)
  • uv tree : 프로젝트의 종속성 트리를 확인할 수 있음
  • uv build : 프로젝트를 배포 아카이브로 빌드함
  • uv publish : 프로젝트를 패키지 인덱스에 게시함

Example

아래의 내용은 uv를 활용하여 django 프로젝트를 설치하고 실행하는 내용 입니다. uv 를 실행하면 자동으로 uv.lock 과 pyproject.toml 등의 설정파일들이 생성됩니다. 이러한 설정파일의 역할은 vite react.js 에서 package.json 의 기능을 생각하면 이해하기 용이 했습니다.

패키지들은 설정파일이 있는 폴더내에 .venv 폴더를 생성하고 그 안에 설치를 합니다. github 등에 자료를 올릴때에는 uv.lock 등의 설정파일만 올리면 되고, 이를 다운받아서 $ uv sync 명령어를 실행하는 방식으로 의존성 패키지 설치가 가능합니다.

$ mkdir website
$ cd website
$ uv init -p 3.12    
Initialized project `website`

$ uv add -r requirements.txt -U

$ tree -L 1 -al                
├── .git
├── .gitignore
├── .python-version
├── .venv  # requirements.txt 등 패키지 설치시 생성
├── README.md
├── main.py
└── pyproject.toml

$ cat pyproject.toml
[project]
name = "website"
version = "0.1.0"
description = "Add your description here"
readme = "README.md"
requires-python = ">=3.12"
dependencies = [
    "django>=5.1.7",
    "uvicorn>=0.34.2",
    "whitenoise>=6.9.0",
]

$ mkdir django
$ cd django
$ uv run django-admin startproject server .

UV in Docker with Django

uv/Using uv in Docker 등을 활용하여 실행은 가능하지만, 운영등의 안정성 측면에서 아직은 검증되지 않았고 실제로도 중간중간 튀는 부분이 있어서 서비스 운영에는 아직은 부적합 합니다.


참고사이트