uv와 가상환경(venv)

uv와 가상환경(venv)

uv와 가상환경(venv)은 같은 것이 아닙니다.
가상환경은 프로젝트를 격리하는 공간이고, uv는 그 공간을 포함해 Python 프로젝트 전체를 관리하는 도구입니다.

가상환경이란?

Python 프로그램마다 필요한 패키지와 버전이 다릅니다.

예를 들어:

• A 프로젝트: Python 3.12, LangChain 0.3
• B 프로젝트: Python 3.11, LangChain 0.2

모든 패키지를 컴퓨터 전체에 한꺼번에 설치하면 버전 충돌이 생길 수 있습니다. 이를 막기 위해 프로젝트마다 독립된 Python 실행 환경을 만드는데, 이것을 가상환경이라고 합니다.

보통 프로젝트 안에 .venv 폴더로 만들어집니다.

03_stream_chat/
├── .venv/          ← 독립된 Python과 패키지 공간
├── main.py
├── pyproject.toml
└── uv.lock

전통적인 방식은 다음과 같습니다.

python -m venv .venv
source .venv/Scripts/activate
pip install langchain-ollama
python main.py
deactivate

즉, 가상환경을 직접 만들고 활성화한 뒤 pip로 패키지를 설치합니다.

uv 환경의 랭체인 프로젝트

uv는 무엇을 하는가?

uv는 가상환경뿐 아니라 다음 작업을 통합 관리합니다.

기능	uv 명령어	의미
Python 준비	uv python install 3.12	필요한 Python 설치
Python 버전 지정	uv python pin 3.12	프로젝트의 Python 버전 고정
프로젝트 생성	uv init	Python 프로젝트 기본 구조 생성
가상환경 생성	uv venv	.venv 가상환경 생성
패키지 추가	uv add 패키지명	패키지 설치 및 목록 기록
환경 동기화	uv sync	설정에 맞게 가상환경 구성
프로그램 실행	uv run python main.py	프로젝트 환경에서 프로그램 실행
패키지 버전 고정	uv.lock	동일한 환경을 다시 만들도록 기록

 

따라서 uv는 venv, pip, Python 버전 관리, 패키지 목록 관리와 실행 기능을 한 도구 안에 모은 것이라고 이해하면 됩니다.

venv와 uv의 핵심 차이

구분	venv	uv
정체	가상환경을 만드는 Python 기본 기능	Python 프로젝트 통합 관리 도구
주요 역할	프로젝트별 환경 격리	환경·Python·패키지·버전·실행 관리
패키지 설치	별도로 pip 사용	uv add, uv sync 사용
패키지 버전 기록	별도 관리 필요	pyproject.toml, uv.lock으로 관리
환경 활성화	일반적으로 필요	uv run 사용 시 불필요
다른 컴퓨터에서 재현	추가 파일과 명령 필요	uv sync로 비교적 간편
설치 속도	일반적인 속도	매우 빠른 편

가장 중요한 관계

uv를 사용한다고 가상환경이 없어지는 것은 아닙니다. uv도 일반적으로 프로젝트 안에 .venv 가상환경을 만들어 사용합니다.

uv
 ├─ Python 버전 관리
 ├─ .venv 가상환경 생성·관리
 ├─ 패키지 설치
 ├─ 의존성 버전 기록
 └─ 프로그램 실행

즉,

가상환경은 격리된 작업실이고, uv는 그 작업실을 만들고 필요한 도구를 배치하며 작업까지 실행해 주는 관리자입니다.

Ollama 실습에서의 작동 과정

현재 사용한 명령은 다음과 같습니다.

uv sync
uv run python main.py

uv sync는 다음 일을 합니다.

1. 현재 폴더에서 pyproject.toml을 찾습니다.
2. 프로젝트가 사용할 Python 버전을 확인합니다.
3. .venv가 없으면 가상환경을 만듭니다.
4. uv.lock에 기록된 정확한 패키지 버전을 확인합니다.
5. 필요한 LangChain 등의 패키지를 .venv에 설치합니다.

uv run python main.py는 다음 일을 합니다.

1. 현재 프로젝트의 .venv를 찾습니다.
2. 해당 환경의 Python을 선택합니다.
3. 필요한 패키지를 사용할 수 있는 상태로 만듭니다.
4. main.py를 실행합니다.

따라서 직접 다음 명령을 실행하지 않아도 됩니다.

source .venv/Scripts/activate

uv run이 실행할 때 자동으로 프로젝트 가상환경을 사용합니다.

uv run python main.py

프로그램이 끝나면 uv가 사용한 실행 환경도 자동으로 종료됩니다.

공용컴퓨터에서 유리한 이유

도서관 컴퓨터처럼 재부팅하면 초기화되는 환경에서는 uv가 특히 편리합니다. GitHub에서 프로젝트를 다시 내려받은 다음, 다음 명령으로 환경을 재구성할 수 있기 때문입니다.

git clone 저장소주소
cd 프로젝트폴더
uv sync
uv run python main.py

단, .venv 자체를 GitHub에 올리는 것이 아니라 다음 파일을 보관해야 합니다.

main.py
pyproject.toml
uv.lock
README.md

새 컴퓨터에서는 uv sync가 이 기록을 읽고 .venv를 다시 만듭니다.

한 문장으로 정리하면:

venv는 프로젝트별로 격리된 Python 실행 공간이고, uv는 그 가상환경을 포함하여 Python 설치, 패키지 의존성, 버전 고정 및 프로그램 실행까지 관리하는 통합 도구입니다.