Python uv 설치 방법 2026: pip 대신 uv를 쓰는 이유와 기본 명령어

uv는 Python 가상환경 생성, 패키지 설치, 프로젝트 실행 흐름을 한 번에 정리할 때 유용합니다.

Python uv는 언제 쓰면 좋을까

Python에서 pip install, venv, requirements.txt를 따로 다루다 보면 설치 위치와 Python 버전이 꼬이는 경우가 많습니다. uv는 이런 과정을 더 빠르고 일관된 명령어 흐름으로 정리해 주는 Python 패키지·프로젝트 관리 도구입니다.

처음부터 모든 도구를 uv로 바꿀 필요는 없습니다. 새 프로젝트를 만들거나, 기존 requirements.txt를 다시 설치하거나, VSCode에서 프로젝트별 인터프리터를 안정적으로 잡고 싶을 때 uv를 먼저 써보면 차이를 체감하기 쉽습니다.

pip, venv, pip-tools와 uv 차이

Python 초보자가 헷갈리는 지점은 “uv가 pip를 대체하나요?”라는 질문입니다. 답은 상황에 따라 다릅니다. 기존 방식의 명령어를 유지하고 싶다면 uv pip를 쓰면 되고, 새 프로젝트를 만들 때는 uv init, uv add, uv run 흐름을 쓰는 편이 깔끔합니다.

도구	주요 역할	uv에서 대응되는 흐름
pip	패키지 설치와 제거	uv pip install, uv add
venv	프로젝트별 가상환경 생성	uv venv
pip-tools	requirements 파일 고정	uv pip compile, uv lock
pyproject.toml	프로젝트 메타데이터와 의존성 선언	uv init, uv add

이미 pip install 오류를 해결한 상태라면 다음 단계는 설치 명령어를 계속 반복하는 것이 아니라, 프로젝트마다 독립된 환경을 만들고 그 환경을 다시 재현할 수 있게 정리하는 것입니다.

macOS, Windows, Linux에서 uv 설치하기

uv는 공식 설치 스크립트, Homebrew, WinGet, Scoop, pipx 등 여러 방식으로 설치할 수 있습니다. 초보자는 공식 설치 스크립트나 운영체제별 패키지 매니저 중 하나만 선택해도 충분합니다.

macOS 설치

macOS에서는 공식 설치 스크립트 또는 Homebrew를 사용할 수 있습니다. Homebrew를 이미 사용하고 있다면 brew install uv가 가장 익숙합니다.

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

# Homebrew를 쓰는 경우
brew install uv

# 설치 확인
uv --version

Windows 설치

Windows에서는 PowerShell에서 설치 스크립트를 실행하거나 WinGet, Scoop을 사용할 수 있습니다. 회사 PC처럼 실행 정책이 제한된 환경에서는 관리자 정책을 먼저 확인하는 것이 좋습니다.

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

# WinGet을 쓰는 경우
winget install --id=astral-sh.uv -e

# 설치 확인
uv --version

Linux 설치

Linux에서는 macOS와 같은 공식 설치 스크립트를 사용할 수 있습니다. 서버나 컨테이너 환경에서는 설치 위치와 PATH가 셸 설정에 반영되었는지 함께 확인해야 합니다.

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

# curl이 없는 경우
wget -qO- https://astral.sh/uv/install.sh | sh

# 설치 확인
uv --version

새 Python 프로젝트 만들기

새 프로젝트를 시작한다면 uv init으로 기본 파일을 만드는 방식이 가장 단순합니다. 이 흐름은 pyproject.toml을 중심으로 의존성을 관리하므로, 나중에 다른 PC에서 같은 환경을 다시 만들기 쉽습니다.

mkdir uv-example
cd uv-example

uv init
uv run main.py

uv init을 실행하면 프로젝트 설정 파일이 만들어지고, uv run으로 현재 프로젝트 환경에서 Python 파일을 실행할 수 있습니다. 단순 스크립트 자동화나 API 테스트 프로젝트를 만들 때 이 흐름부터 익히면 좋습니다.

uv로 가상환경 만들기

기존 Python 방식에서는 python -m venv .venv로 가상환경을 만들고 활성화한 뒤 pip install을 실행했습니다. uv에서는 uv venv로 같은 목적의 가상환경을 만들 수 있습니다.

uv venv

# 특정 Python 버전으로 만들고 싶을 때
uv venv --python 3.12

가상환경을 만든 뒤 활성화 명령어는 운영체제에 따라 다릅니다.

# macOS / Linux
source .venv/bin/activate

# Windows PowerShell
.venv\Scripts\activate

# 종료
deactivate

uv로 패키지 설치하기

uv에서 패키지를 설치하는 방식은 크게 두 가지입니다. 기존 pip 방식에 가깝게 쓰려면 uv pip install을 사용하고, uv 프로젝트 방식으로 관리하려면 uv add를 사용합니다.

기존 pip처럼 설치하기

uv venv
source .venv/bin/activate

uv pip install requests
uv pip install "fastapi[standard]"
uv pip uninstall requests

uv 프로젝트 방식으로 설치하기

uv init
uv add requests
uv add pandas
uv remove requests

uv run python main.py

uv add는 패키지를 설치하면서 프로젝트 의존성 정보도 함께 갱신합니다. 새 프로젝트라면 uv pip install보다 uv add 흐름을 먼저 익히는 편이 관리하기 쉽습니다.

requirements.txt 설치하기

이미 내려받은 프로젝트에 requirements.txt가 있다면 uv로도 설치할 수 있습니다. 먼저 프로젝트 폴더에서 가상환경을 만들고, 그 환경 안에 requirements 파일을 설치하면 됩니다.

cd 기존프로젝트폴더

uv venv
source .venv/bin/activate

uv pip install -r requirements.txt

팀 프로젝트처럼 requirements 파일에 고정된 버전을 정확히 맞춰야 한다면 uv pip sync도 선택지입니다. 이 명령은 파일에 적힌 패키지 상태에 맞추는 성격이 강하므로, 기존 환경에 설치된 다른 패키지가 정리될 수 있다는 점을 알고 사용해야 합니다.

uv pip sync requirements.txt

requirements.txt 설치 중 Python 버전이나 패키지 충돌이 나온다면 먼저 requirements.txt 설치 오류에서 Python 버전과 패키지 충돌을 점검하는 순서를 확인한 뒤 uv 환경을 다시 만드는 편이 안전합니다.

VSCode에서 uv 가상환경 선택하기

uv로 만든 .venv를 VSCode에서 선택하면 프로젝트별 Python 실행 환경을 분리해 관리할 수 있습니다.

VSCode에서 uv를 쓸 때 핵심은 프로젝트 폴더 안의 .venv를 Python 인터프리터로 선택하는 것입니다. uv 자체를 VSCode가 특별하게 인식해야 하는 것이 아니라, uv가 만든 가상환경의 Python 실행 파일을 선택한다고 이해하면 쉽습니다.

1. 프로젝트 폴더에서 uv venv를 실행합니다.
2. VSCode로 같은 프로젝트 폴더를 엽니다.
3. Ctrl + Shift + P 또는 Cmd + Shift + P를 누릅니다.
4. Python: Select Interpreter를 선택합니다.
5. .venv 경로가 포함된 Python을 선택합니다.

# 선택된 Python 경로 확인
python -c "import sys; print(sys.executable)"

출력 경로에 프로젝트 폴더의 .venv가 들어 있으면 정상입니다. 전역 Python이나 다른 conda 환경이 보인다면 VSCode 인터프리터 선택이 아직 맞지 않은 상태입니다.

자주 나는 uv 오류와 점검 순서

uv 자체는 빠르지만, 설치 위치와 PATH, Python 버전, VSCode 설정이 섞이면 처음에는 오류처럼 보일 수 있습니다. 아래 순서대로 확인하면 대부분의 초반 문제를 좁힐 수 있습니다.

uv: command not found

설치는 되었지만 터미널이 uv 실행 파일 위치를 모르는 상태일 수 있습니다. 터미널을 완전히 닫았다가 다시 열고, 그래도 안 되면 PATH에 uv 설치 경로가 들어갔는지 확인합니다.

uv --version

# macOS / Linux에서 위치 확인
which uv

# Windows PowerShell에서 위치 확인
where.exe uv

Python 버전이 맞지 않을 때

프로젝트가 특정 Python 버전을 요구한다면 가상환경을 만들 때 버전을 지정합니다. 이미 잘못 만든 가상환경이라면 .venv를 삭제하고 다시 만드는 편이 빠릅니다.

rm -rf .venv
uv venv --python 3.12

# Windows PowerShell
Remove-Item -Recurse -Force .venv
uv venv --python 3.12

VSCode에서 인터프리터가 안 보일 때

VSCode가 프로젝트 루트가 아닌 상위 폴더를 열고 있으면 .venv를 자동으로 찾지 못할 수 있습니다. 터미널에서 pwd 또는 cd 위치를 확인하고, VSCode에서 실제 프로젝트 폴더를 다시 여는 것이 좋습니다.

requirements.txt 설치가 계속 실패할 때

패키지 자체가 현재 Python 버전을 지원하지 않거나, 오래된 빌드 도구가 필요한 경우가 있습니다. 이때는 uv 명령어만 바꾸기보다 Python 버전, 운영체제, 패키지 버전 제한을 함께 봐야 합니다.

증상	먼저 확인할 것	권장 조치
uv 명령을 찾지 못함	PATH, 터미널 재시작	설치 경로 확인 후 셸 설정 점검
패키지 설치 실패	Python 버전, 패키지 버전	새 .venv 생성 후 다시 설치
VSCode 실행 Python이 다름	선택된 인터프리터 경로	.venv 안의 Python 선택

pip install 오류 글과 함께 보는 순서

uv를 설치했다고 해서 모든 Python 오류가 자동으로 사라지는 것은 아닙니다. 다만 프로젝트별 가상환경을 분리하고, 같은 의존성 상태를 다시 만들 수 있게 해 주기 때문에 반복 오류를 줄이는 데 도움이 됩니다.

1. 현재 프로젝트가 어떤 Python 버전을 요구하는지 확인합니다.
2. .venv를 새로 만들고 VSCode 인터프리터를 맞춥니다.
3. 새 프로젝트는 uv add, 기존 프로젝트는 uv pip install -r requirements.txt를 사용합니다.
4. 설치 실패 메시지에 나온 패키지명과 Python 버전 조건을 확인합니다.
5. PATH 문제라면 Python이 아니라 셸 설정부터 점검합니다.

공식 자료로 더 확인하기

uv는 설치 방식과 명령어 흐름이 계속 개선될 수 있으므로, 실제 개발 환경에 적용하기 전에는 공식 문서에서 운영체제별 설치 방법과 프로젝트 관리 명령어를 함께 확인하는 것이 좋습니다.

함께 보면 좋은 글

자주 묻는 질문

Python uv를 처음 쓸 때는 설치 명령어보다 프로젝트마다 .venv를 분리하고, VSCode가 그 환경을 바라보게 만드는 기준을 먼저 잡는 것이 가장 중요합니다.