Skip to main content

​
UV 프로젝트 환경

도메인별 프로젝트를 uv로 분리하고, uv sync만으로 재현 가능한 형태로 구성합니다.

​
문서 기준

  • 기준일: 2026-02-23
  • Python: 3.12 고정
  • 운영체제: macOS, Ubuntu 24.04+, Windows 11
  • 재현 방식: pyproject.toml 고정 버전 + uv.lock 커밋

​
공통 원칙

  • 프로젝트마다 pyproject.toml과 uv.lock을 분리합니다.
  • 버전은 ==로 고정해 팀 환경 차이를 줄입니다.
  • OS별로 설치가 갈리는 패키지는 환경 마커를 사용합니다.
  • 하위 문서의 pyproject.toml을 그대로 사용한 뒤 uv sync를 실행합니다.

​
공통 실행 순서

1

프로젝트 초기화

uv init <project-name>
cd <project-name>
2

문서의 pyproject.toml 반영

하위 문서의 pyproject.toml 예시를 현재 프로젝트의 pyproject.toml에 반영하세요.
3

락 파일 생성 및 동기화

uv lock
uv sync
4

커널 등록(선택)

uv run python -m ipykernel install --user --name <project-name> --display-name "UV <project-name>"

​
프로젝트별 용도 비교

프로젝트용도핵심 패키지GPU 필수OS 제한
dl-env딥러닝 기본 학습/평가/해석torch, sklearn, shap, mlflow권장없음
rag-devRAG 파이프라인 개발langchain, chromadb, ragas선택faiss: Windows 제외
agent-devAI Agent 개발langgraph, fastapi, openai불필요없음
llm-finetuneLLM 파인튜닝 (SFT/LoRA/QLoRA)transformers, peft, trl, unsloth필수unsloth: Linux x86_64 전용
cv-research컴퓨터 비전 연구ultralytics, timm, albumentations권장없음
automlAutoML 실험 자동화autogluon, flaml, optuna선택autogluon: Windows 제외
vllm-servingLLM 서빙 (OpenAI 호환 API)vllm, ray, transformers필수vllm: Linux x86_64 전용

​
프로젝트 환경 목록

dl-env

Deep Learning 기본 환경 (torch 2.10.0)

rag-dev

RAG 개발 환경 (langchain 1.2.10, ragas 0.4.3)

agent-dev

AI Agent 개발 환경 (langgraph 1.0.9)

llm-finetune

LLM 파인튜닝 (Unsloth 호환: transformers 4.57.6, trl 0.24.0)

cv-research

컴퓨터 비전 연구 (ultralytics 8.4.14)

automl

AutoML 실험 (autogluon 1.5.0, ray 2.52.1)

vllm-serving

vLLM 서빙 (Linux x86_64 기준 vllm 0.15.1)

​
uv 기본 명령어 참고

명령어설명비고
uv init <name>새 프로젝트 초기화pyproject.toml 자동 생성
uv lock의존성 해석 및 uv.lock 생성버전 고정 스냅샷
uv lock --refresh락 파일 갱신충돌 시 사용
uv sync락 파일 기준 환경 동기화가상환경 자동 생성
uv run <cmd>프로젝트 환경에서 명령 실행activate 없이 실행
uv add <pkg>의존성 추가pyproject.toml 자동 반영
uv remove <pkg>의존성 제거pyproject.toml 자동 반영
uv python list설치된 Python 버전 확인버전 관리

​
새 프로젝트 추가 가이드

기존 목록에 없는 새 도메인 환경을 추가하려면 다음 절차를 따르세요.
1

프로젝트 생성 및 의존성 정의

uv init <new-project>
cd <new-project>
pyproject.toml에 requires-python = "==3.12.*", [tool.uv] package = false 를 설정하고, 필요한 패키지를 == 고정 버전으로 추가합니다.
2

OS별 호환성 확인

특정 OS에서 설치 불가능한 패키지는 환경 마커를 사용합니다.
# 예시: Linux x86_64 전용 패키지
"some-pkg==1.0.0; platform_system == 'Linux' and platform_machine == 'x86_64'"
3

락 파일 생성 및 검증

uv lock
uv sync
uv run python -c "import <핵심패키지>; print('OK')"
4

문서 작성

docs/setup/uv-env/<new-project>.mdx 파일을 작성하고, 이 인덱스 페이지의 CardGroup에 항목을 추가합니다.

​
트러블슈팅

증상원인해결
uv sync 실패락 파일이 오래되었거나 손상됨uv lock --refresh 후 uv sync
Python 버전 오류시스템에 3.12 미설치uv python install 3.12
OS별 패키지 누락환경 마커 설정 누락하위 문서의 pyproject.toml 마커 확인
가상환경 경로 충돌기존 .venv 디렉터리 잔존.venv 삭제 후 uv sync 재실행
커널이 Jupyter에 미표시ipykernel install 미실행커널 등록 명령 재실행