today keys : uv, python, rust, package manager, venv, pip, workflow, 가상환경, 패키지관리
이번 포스팅에서는 Rust 기반의 차세대 파이썬 패키지 매니저인 uv의 특징과 초기 설치, 그리고 프로젝트 구성 및 검증 과정을 다룹니다.
UV(Python Package Manager) 도입 배경
기존의 파이썬 생태계는 pyenv(버전 관리), venv(가상환경), pip(패키지 설치) 등 도구가 파편화되어 있어 관리가 번거롭고 속도가 느린 단점이 있었습니다.
uv는 이를 해결하기 위해 모든 기능을 하나로 통합하고, Rust로 제작하여 기존 pip 대비 수십 배 이상의 압도적인 속도를 제공합니다.
[Lab] uv 설치 및 프로젝트 구성 검증
Step 1: uv 설치 및 환경 확인
터미널에서 아래 명령어를 통해 uv를 설치합니다. 별도의 파이썬 설치 없이도 독립적인 바이너리로 동작하는 것이 특징입니다.
macOS/Linux : curl -LsSf https://astral.sh/uv/install.sh | sh
Windows/PowerShell : powershell -c "irm https://astral.sh/uv/install.ps1 | iex"
설치 후 uv --version 명령어로 정상 설치 여부를 확인합니다.
Step 2: 프로젝트 초기화 및 가상환경 구성
새로운 프로젝트 디렉토리를 생성하고 uv init 명령어로 프로젝트를 시작합니다.
mkdir zigi-uv
cd zigi-uv
uv init
"uv init 프로젝트명" 으로 실행하면, 프로젝트 명으로 디렉터리 생성도 자동으로 해줍니다.
uv init 프로젝트명
이후 uv add 명령어를 통해 필요한 패키지를 추가합니다.
이번 포스팅에서는 cowsay 패키지를 추가해서 코드를 만들어 봅니다.
uv add cowsay
uv add를 실행하면, uv는 자동으로 가상환경(.venv)을 생성하고, 패키지 의존성을 고정하는 uv.lock 파일을 생성하여 환경 재현성을 보장합니다.
Step 3: 코드 작성 및 uv run을 통한 실행 검증
기본 생성된 main.py 파일을 다음과 같이 수정합니다.
import cowsay
def main():
cowsay.cow("ZIGI - UV 테스트")
if __name__ == "__main__":
main()
그리고, 수정한 main.py 파일을 실행합니다.
uv run main.py
uv run 명령어를 사용하면 가상환경을 별도로 활성화(activate)하지 않아도 uv가 내부적으로 가상환경 내의 파이썬 인터프리터를 사용하여 즉시 코드를 실행합니다.
위와 같이 소 모양의 아스키 아트와 함께 메시지가 출력된다면, uv를 통한 패키지 격리 및 실행 환경 구성이 정상적으로 완료된 것입니다.
pyproject.toml & uv.lock
UV 환경을 초기화하고, 패키지를 설치하면, pyproject.toml과 uv.lock 파일이 생성되어 있는 것을 볼 수 있습니다.
기존 파이썬 환경에서 패키지 목록을 관리할 때는 requirements.txt에 설치하는 패키지를 기록하여 관리하는 데 이는 단순히 패키지 이름과 버전만 나열된 '리스트'에 불과했습니다.
이 방식은 프로젝트의 전체 메타데이터를 담기 어렵고, 하위 의존성(내가 설치한 패키지가 사용하는 또 다른 패키지)의 버전까지 완벽하게 고정하기 힘들다는 단점이 있었습니다.
UV는 이러한 한계를 극복하기 위해 파이썬 표준인 pyproject.toml과 강력한 환경 재현성을 보장하는 uv.lock 체계를 사용합니다.
pyproject.toml
uv init 시 생성되는 이 파일은 프로젝트의 "의도(Intent)"를 기록합니다. 사용자가 직접 수정하며 프로젝트의 전반적인 방향을 정의하는 역할을 합니다.
- 주요 용도: 프로젝트 메타데이터(이름, 버전, 라이선스 등) 정의
- 필요한 패키지의 범위 지정 (예: requests>=2.31.0)
- 개발용 도구(pytest, black 등) 설정
uv.lock
uv add나 uv lock 실행 시 생성되는 이 파일은 프로젝트의 "상태(State)"를 기록합니다. 시스템이 관리하는 파일로, 사용자가 직접 수정하지 않습니다.
- 주요 용도: 모든 패키지(하위 의존성 포함)의 정확한 버전 고정
- 패키지 간의 복잡한 연결 관계(의존성 트리) 저장
- 빠른 설치를 위한 해시 및 메타데이터 캐싱
