Intro
요즘 fastapi 개발 전략중 uv가 requirements.txt보다 편리한걸로 뽑힌다.
이번 블로그 글에선 간단하게 패키지를 관리하는 방법을 보여주겠다.
진심이다 ㅋ : 아직 나보다 간단하고 전략적으로 구성하는 사람이 없는거 같아서 내글을 남긴다.
이유 :
-
성능(Performance) :
Rust 기반 Resolver로 의존성 설치 속도가 requirements.txt나 poetry 대비 10~100배 빠르다는 공식 벤치마크가 있습니다.
캐싱과 최적화를 적극 활용하여 대규모 프로젝트에서도 빠른 설치 및 업데이트가 가능합니다. -
사용 편의성(Usability) :
uv add 등 단순화된 CLI 명령어로 대부분의 작업을 수행할 수 있습니다.
.venv 폴더나 파이썬 버전 설정(.python-version 등)을 직접 신경 쓰지 않아도 자동으로 생성·관리해줍니다.
들어가기 앞서 구성해야 될 것
requirements의 구성을 목적별로 나누어 구성
아래는 제 requirements.txt 안에 내용에선 용도마다 개념 주석을 씁니다.
패키지 설치와 적용 순서
1. 프로젝트 생성
pip install uv
위와같이 설치 후, 아래를 이행
uv init <프로젝트 이름>
- 아래처럼 구성되게 된다.
<프로젝트 이름>/
├── .python-version
├── main.py
├── pyproject.toml
└── README.md
또는 프로젝트가 이미 있다면 프로젝트 디렉토리(폴더) 안에서 uv init
uv init
2. 통합 requirements.txt인 clean_requirements.txt생성
-
아래의 기능을 사용한 두개 경로 파일이 통합
..\requirements\fastapi-backend-requirements.txt
..\requirements\llm-requirements.txt -
아래는 위 두 경로의 파일을 통합하여 clean_requirements.txt파일 생성
Get-Content ..\requirements\fastapi-backend-requirements.txt, ..\requirements\llm-requirements.txt
| Where-Object { $_ -match '\S' -and $_ -notmatch '^\s*#' }| ForEach-Object { ($ -split '#')[0].Trim() } ` | Where-Object { $ }| ForEach-Object { $_ -replace '\[.*?\]', '' }| Sort-Object | Get-Unique ` | Out-File clean_requirements.txt -Encoding utf8 -
아래는 clean_requirements.txt의 형태
3. pyproject.toml 초반 세팅
- 현재 아래는 설정을 맞추었지만 맨 아래 두개 섹션 추가 해야함
[project] name = "the-project" version = "0.1.0" description = "Add your description here" readme = "README.md" requires-python = ">=3.12" dependencies = [] # 아래 부분을 추가 [dependency-groups] dev = [ "pytest>=8.2.0", ] # 이 부분을 추가하세요 [tool.setuptools.packages.find] include = ["app*"] exclude = ["deploy*", "tests*", "*.egg-info", "__pycache__"]
- 디렉토리 안에 터미널에선 아래 두 섹션을 코드로 추가하기도 한다
uv add --dev "pytest>=8.2.0"
Add-Content pyproject.toml "
n[tool.setuptools.packages.find]" Add-Content pyproject.toml "include = ["app"]" Add-Content pyproject.toml "exclude = ["deploy","tests",".egg-info","pycache`"]"
4. 가상화 + 필요 라이브러리 모음 toml에 추가
-
가상화 환경 venv 생성
uv venv
-
가상화 활성화 (항상 켜놓고 작업 추천)
.venv\Scripts\activate
-
가상화 비활성화
deactivate
-
dependencies = [ ]의 안에 clean_requirements.txt 내용 추가
터미널에서 아래 코드를 치면 자동으로 clean_requirements.txt 내용물이 dependencies에 추가됨uv add -r clean_requirements.txt
-
(선택) [dependency-groups]의 dev 섹션을 생성하여 clean_requirements.txt 내용 추가
터미널에서 아래 코드를 치면 자동으로 clean_requirements.txt 추가됨uv add --dev -r clean_requirements.txt
-
특정 패키지 업데이트가 필요할때는 아래처럼 하면된다. add는 추가/업데이트시 유용
uv add --dev "pytest>=8.1.0"
5. 마무리 패키지 적용 + 운용
-
uv run으로 현재 설치된 패키지 리스트 확인
uv run
-
uv sync만으로 프로젝트에 필요한 Python 버전과 .venv 가 자동으로 맞춰집니다.
uv sync
-
uv lock으로
uv.lock파일을 생성해 의존성 버전을 고정합니다.
빠른 빌드와 재현성을 동시에 보장합니다.uv lock
오류 상황
- 가상 환경이 작동하지 않을 경우
- 가상 환경 폴더 삭제
Remove-Item -Recurse -Force .venv
- venv라는 가상 환경 다시 생성
uv venv
- 가상화 활성화
.venv\Scripts\activate
- 동기화로 마무리
UV SYNC
기타 추가 사항 : 디렉토리 추가
- 디렉토리 생성
New-Item -ItemType Directory -Force -Path app,
"app\models","app\schemas","app\api","app\services","app\utils","app\tasks","app\tests",
"alembic\versions","docker","scripts"
- py 코드 파일 생성 예시
New-Item -ItemType File -Force -Path `
"app__init.py",
"app\main.py",
"app\config.py",
"app\database.py",
"app\models__init.py",
"app\models\user.py",
"app\schemas__init.py",
"app\schemas\user.py",
"app\api__init.py",
"app\api\auth.py",
"app\api\websocket.py",
"app\services__init.py",
"app\services\auth_service.py",
"app\services\redis_service.py",
"app\utils__init.py",
"app\utils\security.py",
"app\utils\dependencies.py",
"app\utils\connection_manager.py",
"app\tasks__init.py",
"app\tasks\tasks.py",
"app\tests__init.py",
"app\tests\test_auth.py",
"app\tests\test_websocket.py",
"app\tests\test_profanity_filter.py",
"alembic\env.py",
"alembic\script.py.mako",
"docker\Dockerfile",
"docker\docker-compose.yml",
"docker\nginx.conf",
"scripts\init_db.py",
"scripts\run_migration.sh",
".env.example",
".gitignore",
"README.md"
