uv로 파이썬 패키지를 관리할때, 파이썬 패키지 설치가 실패하는 케이스(부제: uv workspace)

Python 패키지 관리를 위해 uv를 사용하다가 3시간 동안 삽질한 경험을 공유하고자 합니다. 새로운 파이썬 가상환경을 만들었는데도 패키지 설치가 계속 실패하는 상황이었는데, 알고 보니 uv의 workspace 개념 때문이었습니다.

 

문제 상황

제가 겪은 디렉터리 구조는 다음과 같았습니다. 언뜻 보기에는 별개의 두 uv 프로젝트처럼 보이지만, 실제로는 그렇지 않았습니다.

parent-directory/
├── pyproject.toml
├── uv.lock
└── child-directory/
    └── pyproject.toml

uv Workspace란?

uv에서는 workspace라는 개념이 있습니다. uv 프로젝트 하위에 또 다른 uv 프로젝트를 생성하면, 하위 프로젝트는 자동으로 상위 프로젝트의 workspace 멤버가 됩니다.

• uv workspace 특징
  • 하위 프로젝트는 상위 프로젝트의 uv.lock 파일을 공유합니다
  • 상위 프로젝트의 의존성 관리 정책을 따라갑니다
  • 상위 프로젝트의 pyproject.toml에 자동으로 workspace 멤버로 등록됩니다

 

실제로 상위 디렉터리의 pyproject.toml을 확인해보면, [tool.uv.workspace] 섹션에 하위 프로젝트가 자동으로 추가된 것을 볼 수 있습니다.

[project]
name = "feature-store"
version = "0.1.0"
description = "Add your description here"
readme = "README.md"
requires-python = ">=3.12"
dependencies = [
    "feast>=0.49.0",
]

[tool.uv.workspace]
members = [
    "01_feast",
]

 

문제의 원인

결국 제가 3시간 동안 파이썬 패키지를 설치못한 이유는, uv 프로젝트가 uv workspace로 취급되어 workspace 파이썬 패키지 목록을 공유받았습니다. 공유받은 파이썬 패키지와 새로 설치하려고 하는 파이썬 패키지가 충돌되어 설치를 실패했습니다.

 

해결방법

저의 상황을 해결하려면

1. workspace에서 파이썬 패키지 충돌 문제를 해결하거나
2. workspace에서 uv프로젝트를 제거하면 됩니다.

저는 workspace에서 uv프로젝트를 제거했습니다.

 

Lesson Learn

uv workspace개념을 처음 알게되었고 uv로 파이썬 패키지 설치가 오류났을 경우 workspace의 유/무를 확인할 수 있는 좋은 경험이 되었습니다.