uv와 pyproject.toml 통합 활용 완벽 가이드: 파이썬 프로젝트 관리의 새로운 패러다임

파이썬 프로젝트를 체계적으로 관리하려면 pyproject.toml 파일을 사용하는 것이 점점 더 중요해지고 있습니다. 이 파일은 PEP 518에서 정의된 표준으로, 프로젝트의 의존성, 빌드 도구, 메타데이터 등을 선언하는 데 사용됩니다. uv는 pyproject.toml을 완벽히 지원하며, 이를 통해 더욱 효율적이고 깔끔한 프로젝트 관리를 가능하게 합니다.

이번 글에서는 uv와 pyproject.toml을 통합하여 사용하는 방법을 친절히 설명하고, 따라 하기 쉬운 예제 코드도 함께 제공하겠습니다.

uv와 pyproject.toml 통합 활용 완벽 가이드

---

pyproject.toml이란?

pyproject.toml의 역할

pyproject.toml은 파이썬 프로젝트의 설정 파일로, 다음과 같은 정보를 담을 수 있습니다:

• 프로젝트 메타데이터(이름, 버전, 설명 등)
• 의존성 목록
• 빌드 도구 설정(예: setuptools, poetry 등)
• 개발 환경 설정(예: linting, 테스트 도구)

이 파일은 PEP 518과 PEP 621에 따라 표준화되어 있으며, 다양한 빌드 및 패키지 관리 도구에서 지원됩니다.

---

uv와 pyproject.toml 통합의 장점

uv는 pyproject.toml을 기본으로 사용하여 다음과 같은 작업을 간소화합니다:

1. 중앙 집중식 의존성 관리: 모든 의존성을 한 곳에서 관리할 수 있습니다.
2. PEP 표준 준수: uv는 PEP 518 및 PEP 621 표준을 준수하여 호환성을 보장합니다.
3. 자동화된 동기화: pyproject.toml과 실제 환경 간의 동기화를 자동으로 처리합니다.
4. 가독성 향상: JSON이나 YAML보다 읽기 쉽고 간결한 TOML 형식을 사용합니다.

---

uv로 pyproject.toml 생성하기

uv를 사용하면 pyproject.toml 파일을 손쉽게 생성할 수 있습니다.

기본 파일 생성

새로운 프로젝트를 시작하면서 pyproject.toml 파일을 생성하려면 다음 명령어를 실행하세요:

uv init

이 명령어는 프로젝트 디렉토리에 기본적인 pyproject.toml 파일을 생성합니다.

예제: 생성된 기본 pyproject.toml

[tool.uv]
name = "my_project"
version = "0.1.0"
description = "A sample Python project using uv"
authors = ["Your Name "]
license = "MIT"

[tool.uv.dependencies]
requests = "^2.28"
flask = "^2.2"

[build-system]
requires = ["setuptools", "wheel"]
build-backend = "setuptools.build_meta"

---

의존성 추가 및 관리

uv는 pyproject.toml에 의존성을 추가하고 관리하는 과정을 매우 간단하게 만듭니다.

의존성 추가

다음 명령어를 사용하면 특정 패키지를 설치하고 자동으로 pyproject.toml에 추가할 수 있습니다:

uv add requests flask

개발 의존성 추가

개발 환경에서만 필요한 패키지를 추가하려면 --dev 옵션을 사용하세요:

uv add --dev black pytest

위 명령은 black과 pytest를 개발 의존성으로 추가하며, 이는 tool.uv.dev-dependencies 섹션에 기록됩니다.

의존성 확인

현재 프로젝트의 모든 의존성을 확인하려면 다음 명령어를 실행하세요:

uv list

---

pyproject.toml로부터 환경 동기화

프로젝트를 다른 컴퓨터나 CI/CD 환경에서 실행할 때, pyproject.toml에 정의된 의존성을 기반으로 환경을 재현해야 합니다.

환경 동기화 명령

다음 명령어를 실행하면 pyproject.toml에 정의된 모든 의존성이 설치됩니다:

uv sync

예제: pyproject.toml 동기화 결과

만약 pyproject.toml에 다음과 같은 내용이 있다면:

[tool.uv.dependencies]
requests = "^2.28"
flask = "^2.2"

[tool.uv.dev-dependencies]
pytest = "^7.0"
black = "^23.1"

위 명령어를 실행하면:

• requests, flask: 기본 의존성으로 설치
• pytest, black: 개발 의존성으로 설치

---

빌드 및 배포 설정

uv는 빌드와 배포 작업도 간단히 처리할 수 있도록 지원합니다.

빌드 설정하기

빌드를 위해 필요한 설정은 이미 build-system 섹션에 정의되어 있습니다:

[build-system]
requires = ["setuptools", "wheel"]
build-backend = "setuptools.build_meta"

빌드를 실행하려면 다음 명령어를 사용하세요:

uv build

배포하기

PyPI로 배포하려면 다음 명령어를 실행하세요:

uv publish

이 명령은 빌드를 수행한 후 PyPI에 업로드합니다.

---

고급 설정: 선택적 의존성 관리

선택적 의존성(옵션)을 설정하고 싶다면 다음과 같이 작성할 수 있습니다:

[tool.uv.optional-dependencies]
testing = ["pytest", "pytest-cov"]
docs = ["sphinx", "sphinx-rtd-theme"]

• testing: 테스트 관련 패키지 그룹
• docs: 문서화 관련 패키지 그룹

특정 옵션 그룹만 설치하려면 다음 명령어를 실행하세요:

uv sync --extras testing

---

결론

이번 글에서는 uv와 pyproject.toml을 통합하여 사용하는 방법을 알아보았습니다. uv는 파이썬 프로젝트 관리를 더욱 간편하게 만들어 주며, 특히 PEP 표준을 준수하는 pyproject.toml 파일과의 통합은 큰 장점입니다.

다음 글에서는 uv의 캐시 및 속도 최적화 기법에 대해 다룰 예정입니다. uv의 강력한 성능 최적화 기능을 활용해 더 빠르고 효율적인 개발 환경을 구축해보세요!

UV 캐시 및 속도 최적화 기법: 파이썬 패키지 관리의 새로운 차원

UV 캐시 및 속도 최적화 기법: 파이썬 패키지 관리의 새로운 차원