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를 실행합니다.

공통 실행 순서

프로젝트 초기화

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

문서의 pyproject.toml 반영

하위 문서의 pyproject.toml 예시를 현재 프로젝트의 pyproject.toml에 반영합니다.

락 파일 생성 및 동기화

uv lock
uv sync

커널 등록(선택)

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

프로젝트별 용도 비교

프로젝트	용도	핵심 패키지	GPU 필수	OS 제한
`dl-env`	딥러닝 기본 학습/평가/해석	torch, sklearn, shap, mlflow	권장	없음
`rag-dev`	RAG 파이프라인 개발	langchain, chromadb, ragas	선택	faiss: Windows 제외
`agent-dev`	AI Agent 개발	langgraph, fastapi, openai	불필요	없음
`llm-finetune`	LLM 파인튜닝 (SFT/LoRA/QLoRA)	transformers, peft, trl, unsloth	필수	unsloth: Linux x86_64 전용
`cv-research`	컴퓨터 비전 연구	ultralytics, timm, albumentations	권장	없음
`automl`	AutoML 실험 자동화	autogluon, flaml, optuna	선택	autogluon: Windows 제외
`vllm-serving`	LLM 서빙 (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 버전 확인	버전 관리

새 프로젝트 추가 가이드

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

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

uv init <new-project>
cd <new-project>

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

OS별 호환성 확인

특정 OS에서 설치 불가능한 패키지는 환경 마커를 사용합니다.

# 예시: Linux x86_64 전용 패키지
"some-pkg==1.0.0; platform_system == 'Linux' and platform_machine == 'x86_64'"

락 파일 생성 및 검증

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

문서 작성

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` 미실행	커널 등록 명령 재실행

설치 점검 목록

관리자 권한/필수 도구 등 사전 요구사항을 먼저 확인했습니다.
설치 후 버전 확인 명령어(--version)를 실행해 정상 설치를 검증했습니다.
PATH/환경변수 변경이 필요한 경우 터미널을 다시 열어 적용 여부를 확인했습니다.
문제가 생겼을 때를 대비해 설치 로그 또는 스크린샷을 남겼습니다.

Setup 홈

운영체제별 설치 흐름을 다시 확인합니다.

다음: dl-env

다음 설치 단계를 이어서 진행합니다.

00. 배움 에이아이 소개

01. OS별 개발환경

02. 컨테이너 스택

03. Python 환경 설정

문서 기준

공통 원칙

공통 실행 순서

프로젝트별 용도 비교

프로젝트 환경 목록

dl-env

rag-dev

agent-dev

llm-finetune

cv-research

automl

vllm-serving

uv 기본 명령어 참고

새 프로젝트 추가 가이드

트러블슈팅

설치 점검 목록

관련 문서

Setup 홈

다음: dl-env

​문서 기준

​공통 원칙

​공통 실행 순서

​프로젝트별 용도 비교

​프로젝트 환경 목록

dl-env

rag-dev

agent-dev

llm-finetune

cv-research

automl

vllm-serving

​uv 기본 명령어 참고

​새 프로젝트 추가 가이드

​트러블슈팅

​설치 점검 목록

​관련 문서

Setup 홈

다음: dl-env

문서 기준

공통 원칙

공통 실행 순서

프로젝트별 용도 비교

프로젝트 환경 목록

uv 기본 명령어 참고

새 프로젝트 추가 가이드

트러블슈팅

설치 점검 목록

관련 문서