게시 됨 업데이트 됨15분안에 읽기 (약 2197 단어)

uv 가상환경

파이썬 생태계에서 최근 가장 주목받는 도구인 uv는 Rust로 작성되어 기존의 pip나 poetry보다 훨씬 빠른 속도를 자랑합니다. 설치부터 가상환경 생성까지의 과정을 핵심만 정리해 드릴게요.

1. uv 설치하기

운영체제에 따라 터미널(또는 CMD)에서 아래 명령어를 입력하세요.

macOS / Linux

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

Windows

PowerShell을 열고 아래 명령어를 실행하세요.

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

Tip: 설치가 완료된 후 터미널을 껐다 켜거나 source $HOME/.cargo/env (Unix 기준)를 실행해야 uv 명령어가 인식됩니다.

2. 가상환경 생성 및 활성화

uv는 프로젝트 단위의 워크플로우를 권장합니다.

프로젝트 초기화 (권장)

새 프로젝트 폴더를 만들고 uv 설정을 초기화합니다. 이 과정에서 .venv 가상환경이 자동으로 준비될 준비를 마칩니다.

1
2
3
4
mkdir my-project
cd my-project
uv init

가상환경 직접 생성

특정 버전을 지정하거나 직접 가상환경을 만들고 싶을 때 사용합니다.

1
2
3
4
5
6
# 기본 파이썬 버전으로 생성
uv venv

# 특정 파이썬 버전 지정 (설치되어 있지 않으면 자동으로 다운로드함!)
uv venv --python 3.12

가상환경 활성화

생성된 .venv 폴더 안의 스크립트를 실행합니다.

  • macOS / Linux: source .venv/bin/activate
  • Windows: .venv\Scripts\activate

3. 패키지 설치 및 관리

uv의 진가는 패키지 설치 속도에서 나타납니다.

  • 패키지 추가: uv add requests (자동으로 pyproject.toml에 기록됨)
  • 패키지 삭제: uv remove requests
  • 전체 동기화: uv sync (프로젝트 설정에 맞게 환경을 일치시킴)

uv add

uv에서 현재 프로젝트의 패키지를 최신 버전으로 업그레이드하는 방법은 매우 간단하고 직관적입니다.

상황에 따라 아래의 명령어 중 하나를 선택해 사용하시면 됩니다.

1. 특정 패키지만 하나씩 업그레이드할 때 (uv add)

기존에 설치된 특정 패키지를 최신 버전으로 올리고 싶다면, 패키지를 처음 설치할 때와 동일하게 uv add 명령어를 사용하되 --upgrade 옵션을 붙여주면 됩니다.

1
2
uv add --upgrade requests

  • 결과: requests 패키지가 최신 버전으로 업데이트되며, 이와 연동된 pyproject.toml과 uv.lock 파일이 자동으로 갱신됩니다.

2. 프로젝트의 모든 패키지를 한꺼번에 업그레이드할 때 (uv lock --upgrade)

pyproject.toml에 적힌 허용 범위 내에서 모든 의존성 패키지를 한 번에 최신 버전으로 끌어올리고 싶을 때 사용합니다.

1
2
3
4
5
6
# 1단계: 설계도(uv.lock)를 최신 버전 기준으로 새로 고침
uv lock --upgrade

# 2단계: 새로 고쳐진 설계도에 맞춰 실제 가상환경(.venv)에 설치
uv sync

  • 결과: 모든 패키지의 최신 버전 조합을 다시 계산하여 uv.lock을 바꾸고, uv sync를 통해 내 가상환경을 완전히 최신 상태로 바꿉니다.

3. 만약 기존 pip 스타일(독립형 venv)을 쓰고 계신다면 (uv pip)

pyproject.toml 중심의 프로젝트 방식이 아니라, uv venv로 만든 일반 가상환경에서 전통적인 방식으로 패키지를 올리고 싶다면 uv pip install에 -U (또는 --upgrade) 옵션을 주면 됩니다.

1
2
3
4
uv pip install -U requests
# 또는 모든 패키지 일괄 업그레이드 (requirements.txt 기준)
uv pip install -U -r requirements.txt

💡 보너스 팁: 사용 중인 uv 도구 자체를 업그레이드하려면?

패키지가 아니라 터미널에서 쓰고 계신 uv 명령어 자체를 최신 버전으로 바꿀 때는 아래 명령어를 치시면 됩니다.

1
2
uv self update

tool 사용

네, 당연히 가능합니다! 기존 프로젝트에서 requirements.txt를 사용 중이었다면, uv는 이를 아주 스마트하게 흡수하여 pyproject.toml 기반의 현대적인 프로젝트로 전환해 줍니다.

상황에 따라 두 가지 방법으로 사용할 수 있습니다.

1. requirements.txt의 내용을 프로젝트 의존성으로 추가하기

기존의 파일 내용을 읽어서 pyproject.toml의 [project.dependencies] 항목에 한꺼번에 등록하고 싶을 때 사용합니다.

1
2
3
# requirements.txt에 적힌 모든 패키지를 현재 프로젝트에 추가
uv add -r requirements.txt

  • 작동 방식: uv가 파일을 읽어 패키지 목록을 파악한 뒤, 최적의 버전을 계산하여 pyproject.toml에 기록하고 가상환경에 설치합니다.

2. requirements.txt 파일을 그대로 사용하여 패키지만 설치하기

프로젝트 구조를 바꾸지 않고, 단순히 가상환경에 패키지만 빠르게 깔고 싶을 때 사용합니다. (기존 pip install -r의 초고속 버전이라고 보시면 됩니다.)

1
2
3
# 가상환경에 패키지만 설치 (pyproject.toml 기록 안 함)
uv pip install -r requirements.txt

  • 작동 방식: pyproject.toml은 건드리지 않고, 지정된 가상환경에 패키지만 즉시 설치합니다.

3. uv와 기존 pip의 관리 방식 차이

특징 requirements.txt (기존) uv / pyproject.toml (현대적)
파일 성격 단순 패키지 나열 리스트 프로젝트 설정 및 메타데이터 포함
의존성 해결 설치 순서에 따라 충돌 가능성 있음 모든 패키지 관계를 계산하여 최적화
잠금 파일 보통 없음 (필요 시 pip freeze) uv.lock 파일이 모든 버전 고정

💡 유용한 팁: 반대로 내보내기

uv를 사용 중인데, 아직 uv를 쓰지 않는 서버나 동료를 위해 다시 requirements.txt를 만들어야 한다면 아래 명령어를 사용하세요.

1
2
3
# 현재 프로젝트의 lock 파일을 기반으로 requirements.txt 생성
uv export --format requirements-txt > requirements.txt

결론적으로:

기존 프로젝트를 uv로 마이그레이션하고 싶다면 uv add -r requirements.txt를 적극 추천합니다. 이렇게 하면 이후부터는 requirements.txt 관리의 고통에서 벗어나 pyproject.toml 하나로 모든 것을 관리할 수 있게 됩니다!

혹시 requirements.txt에 특정 버전이 복잡하게 꼬여 있나요? uv는 그 충돌을 찾는 속도도 굉장히 빠르니 바로 시도해 보세요.

tool

1
$ uv tool install open-webui

Remove unused cache entries:

1
uv cache prune

코드를 사용할 때는 주의가 필요합니다.

Clear the entire cache directory:

1
uv cache clean

코드를 사용할 때는 주의가 필요합니다.

rm -rf “$(uv tool dir)”

powershellRemove-Item -Recurse -Force (uv tool dir)

uv를 사용하다 보면 uvx라는 명령어를 마주하게 됩니다. 결론부터 말씀드리면, uv는 프로젝트의 관리와 패키지 설치를 담당하고, uvx는 도구를 설치 없이 바로 실행할 때 사용합니다.

마치 Node.js 생태계의 npm과 npx 관계와 매우 흡사합니다.

1. uv (The Package & Project Manager)

uv는 프로젝트의 의존성을 관리하고, 가상환경을 구축하며, 패키지를 설치하는 메인 관리자입니다.

  • 주요 역할: 패키지 설치, 파이썬 버전 관리, 가상환경 생성, 프로젝트 빌드.

  • 사용 예시:

    1
    2
    3
    4
    uv add requests          # 현재 프로젝트에 requests 설치
    uv run main.py           # 현재 프로젝트 환경에서 스크립트 실행
    uv sync                  # pyproject.toml 기반으로 환경 동기화

  • 특징: 프로젝트 폴더 내의 .venv 또는 pyproject.toml과 밀접하게 연동됩니다.

2. uvx (The Tool Runner)

uvx는 ‘uv tool run’의 줄임말로, 특정 파이썬 도구를 설치하지 않고 즉석에서 실행하고 싶을 때 사용합니다.

  • 주요 역할: 전역적으로 설치하기엔 부담스럽지만, 일회성으로 써야 하는 도구(CLI)를 실행할 때 사용합니다.
  • 작동 방식: 실행 시 임시 가상환경을 만들고, 도구를 다운로드하여 실행한 뒤 종료합니다. (나중에 다시 실행할 때는 캐시된 버전을 사용해 매우 빠릅니다.)
  • 사용 예시:
    1
    2
    3
    4
    uvx ruff check .        # Ruff(린터)를 설치 없이 현재 폴더에서 실행
    uvx cowsay "Hello UV"   # cowsay 도구를 즉석에서 실행
    uvx httpie google.com   # HTTP 요청 도구인 httpie를 즉석에서 실행

https://thinkbee.github.io/python-uv-usages-0ca3beddfe40/

Author

Gangtai Goh

Posted on

2026-07-23

Updated on

2026-07-26

Licensed under

최근 글

×