프로젝트 작업하기¶

uv는 pyproject.toml 파일에 의존성을 정의하는 Python 프로젝트 관리를 지원한다.

새 프로젝트 생성하기¶

uv init 명령어를 사용해 새로운 Python 프로젝트를 생성할 수 있다:

$ uv init hello-world
$ cd hello-world

또는 현재 작업 디렉토리에서 프로젝트를 초기화할 수도 있다:

$ mkdir hello-world
$ cd hello-world
$ uv init

uv는 다음과 같은 파일들을 생성한다:

.
├── .python-version
├── README.md
├── main.py
└── pyproject.toml

main.py 파일은 간단한 "Hello world" 프로그램을 포함한다. uv run 명령어로 실행해 보자:

$ uv run main.py
Hello from hello-world!

프로젝트 구조¶

프로젝트는 몇 가지 중요한 부분으로 구성되어 있으며, 이들이 함께 작동하여 uv가 프로젝트를 관리할 수 있게 한다. uv init으로 생성된 파일 외에도, uv는 프로젝트 명령어(예: uv run, uv sync, uv lock)를 처음 실행할 때 프로젝트 루트에 가상 환경과 uv.lock 파일을 생성한다.

완전한 프로젝트 구조는 다음과 같다:

.
├── .venv
│   ├── bin
│   ├── lib
│   └── pyvenv.cfg
├── .python-version
├── README.md
├── main.py
├── pyproject.toml
└── uv.lock

`pyproject.toml`¶

pyproject.toml 파일은 프로젝트의 메타데이터를 포함한다:

pyproject.toml

[project]
name = "hello-world"
version = "0.1.0"
description = "여기에 설명을 추가하세요"
readme = "README.md"
dependencies = []

이 파일을 사용해 의존성을 지정하고, 프로젝트의 설명이나 라이선스와 같은 세부 정보를 정의한다. 파일을 직접 수정하거나, uv add 및 uv remove 같은 커맨드라인 명령어를 사용해 프로젝트를 관리할 수 있다.

Tip

pyproject.toml 형식을 시작하는 방법에 대한 자세한 내용은 공식 pyproject.toml 가이드를 참고한다.

이 파일은 uv 설정 옵션을 [tool.uv] 섹션에 지정하는 데에도 사용한다.

`.python-version`¶

.python-version 파일은 프로젝트의 기본 Python 버전을 포함한다. 이 파일은 uv가 프로젝트의 가상 환경을 생성할 때 사용할 Python 버전을 지정한다.

`.venv`¶

.venv 폴더는 프로젝트의 가상 환경을 포함한다. 이 가상 환경은 시스템의 다른 부분과 격리된 Python 환경이다. uv는 이곳에 프로젝트의 의존성을 설치한다.

자세한 내용은 프로젝트 환경 문서를 참고한다.

`uv.lock`¶

uv.lock은 프로젝트의 의존성에 대한 정확한 정보를 담은 크로스 플랫폼 lockfile이다. 프로젝트의 전반적인 요구 사항을 명시하는 pyproject.toml과 달리, lockfile은 프로젝트 환경에 설치된 정확한 버전 정보를 포함한다. 이 파일은 버전 관리 시스템에 체크인해야 하며, 이를 통해 여러 머신에서 일관되고 재현 가능한 설치 환경을 보장한다.

uv.lock은 사람이 읽을 수 있는 TOML 파일이지만, uv에 의해 관리되며 수동으로 편집하면 안 된다.

더 자세한 내용은 lockfile 문서를 참조한다.

의존성 관리¶

pyproject.toml에 의존성을 추가하려면 uv add 커맨드를 사용한다. 이 명령어는 락파일과 프로젝트 환경도 함께 업데이트한다:

$ uv add requests

버전 제약 조건이나 대체 소스를 지정할 수도 있다:

$ # 버전 제약 조건 지정
$ uv add 'requests==2.31.0'

$ # git 의존성 추가
$ uv add git+https://github.com/psf/requests

패키지를 제거하려면 uv remove를 사용한다:

$ uv remove requests

패키지를 업그레이드하려면 --upgrade-package 플래그와 함께 uv lock을 실행한다:

$ uv lock --upgrade-package requests

--upgrade-package 플래그는 지정한 패키지를 최신 호환 버전으로 업데이트하려고 시도하며, 나머지 락파일은 그대로 유지한다.

자세한 내용은 의존성 관리 문서를 참고한다.

커맨드 실행¶

uv run은 프로젝트 환경에서 임의의 스크립트나 커맨드를 실행할 때 사용한다.

uv run을 호출하기 전에, uv는 pyproject.toml과 lockfile이 최신 상태인지 확인하고, 환경이 lockfile과 일치하는지 검사한다. 이를 통해 프로젝트가 동기화된 상태를 유지하며 수동 개입 없이도 일관성을 보장한다. uv run은 커맨드가 일관적이고 잠긴 환경에서 실행되도록 한다.

예를 들어, flask를 사용하려면 다음과 같이 실행한다:

$ uv add flask
$ uv run -- flask run -p 3000

또는 스크립트를 실행하려면:

example.py

# 프로젝트 의존성 필요
import flask

print("hello world")

$ uv run example.py

또는 uv sync를 사용해 환경을 수동으로 업데이트한 후 활성화하고 커맨드를 실행할 수도 있다:

=== "macOS와 Linux"

```console
$ uv sync
$ source .venv/bin/activate
$ flask run -p 3000
$ python example.py
```

=== "Windows"

```powershell
uv sync
source .venv\Scripts\activate
flask run -p 3000
python example.py
```

참고

uv run 없이 프로젝트에서 스크립트와 커맨드를 실행하려면 가상 환경이 활성화되어 있어야 한다. 가상 환경 활성화는 셸과 플랫폼마다 다르다.

자세한 내용은 프로젝트에서 커맨드와 스크립트 실행 문서를 참고한다.

배포 파일 생성하기¶

uv build 명령어를 사용하면 프로젝트의 소스 배포 파일과 바이너리 배포 파일(wheel)을 생성할 수 있다.

기본적으로 uv build는 현재 디렉터리에 있는 프로젝트를 빌드하고, 생성된 파일을 dist/ 하위 디렉터리에 저장한다:

$ uv build
$ ls dist/
hello-world-0.1.0-py3-none-any.whl
hello-world-0.1.0.tar.gz

자세한 내용은 프로젝트 빌드 문서를 참고한다.

다음 단계¶

uv와 함께 프로젝트를 진행하는 방법을 더 알아보려면 프로젝트 개념 페이지와 커맨드라인 참조를 확인한다.

또는, 프로젝트를 빌드하고 패키지 인덱스에 배포하는 방법을 계속 읽어본다.