Python - uv 패키지, 프로젝트 관리자 설치 및 사용법

오늘은 요즘 핫하다고 할 수 있는 uv를 이용해서 설치와 기본 사용법에 대해서 설명해보고자 한다.

uv는 Python 패키지와 프로젝트를 관리할 수 있는데, pip 의 차기 버전이라고 할 수 있을 정도로 빠른 속도와 관리의 편의성을 제공한다.

pip의 기존 문제점이라고 하기는 어렵지만, pip는 쉽게 사용할 수 있는 장점이 있는 반면에 프로젝트별 버전관리의 불편함과 느린 속도가 큰 문제점이다. uv는 프로젝트 관리와 패키지 관리를 일원화 하여 편의성을 높이고,(npm 같은 느낌)
패키지를 설치하는데도 기존 pip보다 빠르게 구성되어 많은 최적화가 되어진 모습을 보여준다.

또 기존에 Python의 버전 설치에 대한 부분도 함께 해결된다는 점은 큰 장점이라고 생각되며, 패키지 관리 역시 요즘 통합되고 있는 pyproject.toml 으로 관리된다는 점도 좋다. 즉, 

uv를 이용해서 프로젝트와 패키지 관리를 동시에 진행할 수 있다.

 

1. uv 설치

uv설치는 아래 Install에서 Powershell 과 Linuxshell에서 설치가 가능하다.

Windows는 powershell 기준으로 동작한다.

powershell
Set-ExecutionPolicy RemoteSigned -scope CurrentUser
irm https://astral.sh/uv/install.ps1 | iex

Linux는 아래와 같이 가능하며,

curl -LsSf https://astral.sh/uv/install.sh | less

Mac의 경우 blew를 이용할 수 있다.

brew install uv

 

설치를 해서 보면, 버전이 2025년1월6일 기준으로 0.5.15 버전이 설치되는데, 현재 버전이 빠르게 올라가고 있다는 점을 참고하면 좋을 것 같다.

 

필자의 윈도우 기준 설치는 아래와 같이 진행된다.

2. uv 사용법

uv에는 다양한 기능이 있는데,  여기에서는 가장 기본적으로 많이 사용되는 명령어 몇가지를 추려보았다.

여기에서는 python, init, add, sync, run 에 대해서 프로젝트를 간단히 생성하면서, 알아보도록 하자.

 

2.1 uv python - 파이썬 설치 

필자가 생각하는 큰 장점중 하나로 Python 버전을 관리하는 부분이다. Python은 특성상 독립적으로 설치하거나, 버전별로 전역으로 설치해서 사용하는데, venv등을 이용해서 관리가 필요한데, 이를 uv를 이용할 경우 통합 관리할 수 있다.

uv python list를 이용하면 현재 설치된 Python 목록과 설치가 가능한 버전들을 확인 할 수 있다.

필자는 과거 설치한 3.11, 3.12 버전을 확인할 수 있었고 그외 설치가 가능한 버전들도 확인 할 수 있다.

현재 설치된 버전과 위치, 설치 가능버전들 확인

uv python install 명령을 이용해서 Python을 추가로 설치하고 싶다면, 설치가 가능하다. 3.13 과 같이 버전 두번째 자리까지 작성하면 해당 버전의 안정화 버전으로 List 명령으로 확인된 기준으로 설치된다. 그럼 python 3.13 버전을 설치해 보자.

uv python install 3.13

설치후 list 명령을 이용해서 확인해 보면, 3.13의 안정화 버전인 cpython-3.13.1-windows-x86_64-none 가 설치된 것을 알 수 있다.

uv로 pyhon 버전 설치 및 관리

uv venv 을 이용해서 가상화 환경도 구성할 수 있다는 점도 알아두기 바란다.

2.2 uv init - 프로젝트 생성

uv init 로 프로젝트를 생성할 수 있다.

이를 이용하게 되면, 프로젝트의 기초 설계를 진행할 수 있게 된다. 만약 별다른 입력없이 사용할 경우 현재 전역으로 사용되는 Python을 기준으로 파일이 생성되고, pyproject.toml 및 venv등이 자동으로 만들어 진다.

uv init

만약 프로젝트에 사용할 Python 파일이 3.13인 경우  -p 3.13 을 이용하면 된다.

uv init -p 3.13

프로젝트의 기본 관리는 pyproject.toml을 이용해서 관리되므로, 잘못생성한 경우 이 파일을 지우고 새로 구성하면 된다.

3.13으로 변경

그리고 필자는 uvtest라는 폴더를 미리 만들었는데, 이경우 uv init를 통해 현재 경로를 프로젝트 경로로 사용하게 된다.

별도의 프로젝트 폴더를 함께 생성하고자 한다면,

init 뒤에 프로젝트이름 을 작성하면 해당 폴더를 생성하고 설정 파일들이 위치하게 된다.

uv init uvtest2 -p 3.12

 

2.3 uv add - 패키지 설치

이부분이 nodejs와 비슷한 느낌이 많이 드는 부분으로, add 명령을 이용해서 패키지를 설치할 수 있다.

(삭제는 remove로 가)

만약 fastapi를 설치하고 싶다면, 아래와 같이 진행할 수 있다.

uv add fastapi

패키지를 설치해보면 느끼겠지만, 정말 빠르게 설치된다.

그리고 pyproject.toml 을 위해서 빌드를 생각한다면, 마지막에 개발 의존성 옵션인 --dev 를 입력하면 pyproject.toml 과 uv.lock에 해당 라이브러리를 기록하여, 추후 빌드, 배포등을 관리할 수 있도록 도움을 준다.

 

추가로 간혈적으로 라이브러리에 추가 옵션이 붙는 경우를 보았을 것이다. 대표적으로 fastapi와 많이 사용하는 uvicorn이 있는데, pip를 이용할 경우에는 "uvicorn[standard]" 명령을 사용하였는데, uv에서는 --extra 옵션을 사용해서 해결할 수 있다.

// pip
pip install "uvicorn[standard]"

//uv
uv add uvicorn --extra standard --dev

 

2.4 uv sync - 의존성 설치

uv 명령에서 패키지 및 프로젝트와 관련된 설정의 세부 내용들은 uv.lock 에서 관리된다.

내용을 보면 패키지별 세부적인 내용들까지 관리되고 있는 것을 알 수 있다.

이는 다른 프로젝트를 내 로컬로 가져왔을 때  uv sync를 통해서, 손쉽게 패키지를 설치할 수 있게 된다.

특히 uv의 가장 좋은 점은 기본적으로 가상환경으로 운영되도록 되어 있어서 프로젝트의 독립적운영이 편리하는 것이다.

 

2.5 uv run - 프로젝트 실행

앞서 uv python 을 이용해서 uv에서 Python의 버전을 관리하는 것을 알 수 있었다.

uv run은 uv.lock 파일을 통해서 현재 프로젝트의 Python 버전을 확인하고, 자동으로 해당 버전을 이용하여 프로젝트를 구동해주는 역활을 한다. 

만약 fastapi 를 실행하고자 한다면, main.py를 작성하고, 아래 명령을 실행하는 것만으로 가상환경으로 실행해주게 된다.

uv run main.py

 

2.6 uv pip, exprot - legacy  지원 (pip, requirements.txt)

현재 uv 명령으로도 관리하는데 불편함이 없지만, 기존 pip와 equirements.txt의 필요할 경우가 있다. 이때

uv pip를 이용해서 uv에서 패키지 설치를 지원한다. 다만 pip를 이용할 경우에는 pyproject.toml과 uv.lock 는 이를 기록하지 않기 때문에 로컬 환경에서만 임시적으로 필요할 때에만 사용하는 것을 추천한다. 

uv pip install mysql

uv export를 명령을 통해서 pip 명령과 동일하게  requirements.txt를 작성할 수 있다. 이를 통해서 

uv export -o requirements.txt

마치며

드디어 Python도 프로젝트처럼 관리하는 프레임워크가 제대로 나온것 같은 느낌에 기쁘다.

특히 설치 속도가 빠르다는 점은, 최적화가 잘되어 있는 느낌이 강해서 아주 기대되는 프로젝트이다.

Python을 사용하시는 분이라면 꼭 uv를 이용해서 프로젝트를 관리해보시기를 추천한다.

참고

uv

uv