# UV Workspaces를 사용한 파이썬 모노레포 관리

> Clean Markdown view of GeekNews topic #24245. Use the original source for factual precision when an external source URL is present.

## Metadata

- GeekNews HTML: [https://news.hada.io/topic?id=24245](https://news.hada.io/topic?id=24245)
- GeekNews Markdown: [https://news.hada.io/topic/24245.md](https://news.hada.io/topic/24245.md)
- Type: news
- Author: [darjeeling](https://news.hada.io/@darjeeling)
- Published: 2025-11-09T20:51:23+09:00
- Updated: 2025-11-09T20:51:23+09:00
- Original source: [secondb.ai](https://secondb.ai/summary/7276/)
- Points: 18
- Comments: 1

## Summary

여러 개의 **파이썬 앱을 하나의 레포지토리**에서 다루는 개발자라면, **UV Workspaces**가 꽤 반가운 도구일 것입니다. 루트 단일 **가상환경과 공유 의존성 관리**, 그리고 **내부 패키지를 통한 코드 재사용**을 지원해, CLI·API 등 서로 다른 앱 간의 중복 코드와 버전 충돌 문제를 깔끔히 정리합니다. `uv sync` 한 번으로 모든 하위 프로젝트를 일관된 환경에서 실행할 수 있어, 모노레포 운영이 훨씬 단순해집니다. 작은 팀이 여러 유틸리티를 함께 관리하는 구조라면, 이 워크플로우가 개발 효율을 크게 높여줄 듯합니다.

## Topic Body

### UV Workspaces를 사용한 파이썬 모노레포 관리 요약  
  
이 영상은 단일 깃(Git) 레포지토리에서 여러 개의 파이썬 애플리케이션(모노레포)을 관리할 때 발생하는 문제점들을 **UV Workspaces** 기능을 사용하여 깔끔하게 해결하는 방법을 소개합니다.  
  
#### 1. 영상 요약  
  
##### 문제점  
하나의 레포지토리에서 CLI 도구와 FastAPI 앱을 동시에 개발할 때, 다음과 같은 문제들이 발생합니다.  
* **코드 중복**: CLI와 API에서 공통으로 사용하는 기능(예: 헤드라인 크롤링 함수)을 복사/붙여넣기 해야 합니다.  
* **복잡한 환경 관리**: 각 앱마다 별도의 가상 환경을 관리해야 하므로, 의존성 버전이 충돌하거나 디스크 공간이 낭비됩니다.  
  
##### 해결책: UV Workspaces  
UV Workspaces는 이러한 문제들을 해결하기 위해 두 가지 핵심 기능을 제공합니다.  
  
1.  **공유 의존성 및 단일 가상 환경**  
    * 프로젝트 루트(최상위)에 있는 `pyproject.toml` 파일에서 공통 의존성을 정의할 수 있습니다.  
    * `uv sync` 명령어를 실행하면, UV가 이 설정 파일을 읽어 레포지토리 전체에서 공유하는 **단일 가상 환경**(.venv)을 루트 폴더에 생성합니다.  
    * 이를 통해 모든 하위 프로젝트(CLI, API 등)가 동일한 환경과 의존성을 공유하게 되어 버전 충돌을 방지하고 관리가 용이해집니다.  
  
2.  **내부 패키지를 통한 코드 공유**  
    * 중복되는 공통 코드(예: `fetch_headlines` 함수)를 `core`와 같은 별도의 "내부 패키지"로 분리할 수 있습니다.  
    * 워크스페이스 설정을 통해 이 `core` 패키지를 PyPI가 아닌 로컬 소스로 인식시킵니다.  
    * 이제 CLI 앱과 API 앱에서 `from core.news import fetch_headlines`와 같이 이 공통 코드를 `import`하여 재사용할 수 있습니다.  
  
#### 2. UV Workspaces 사용 방법  
  
##### 1단계: 워크스페이스 설정  
프로젝트 루트 폴더에 `pyproject.toml` 파일을 만들고, `[tool.uv.workspace]` 섹션을 정의하여 하위 프로젝트들이 어디에 있는지 알려줍니다.  
  
```toml  
[tool.uv.workspace]  
# "packages" 폴더 내의 모든 하위 폴더를 워크스페이스 멤버로 인식  
members = ["packages/*"]  
````  
  
##### 2단계: 의존성 관리  
  
  * **공유 의존성**: 모든 프로젝트가 공통으로 쓰는 의존성(예: `python-dotenv`)은 \*\*루트 `pyproject.toml`\*\*에 추가합니다.  
  * **개별 의존성**: 특정 앱(예: `api`)에서만 사용하는 의존성(예: `fastapi`, `uvicorn`)은 **해당 앱의 `pyproject.toml`** (예: `packages/api/pyproject.toml`)에 추가합니다.  
  * 루트 폴더에서 `uv sync`를 실행하면, UV가 모든 `pyproject.toml`을 스캔하여 루트 가상 환경에 필요한 모든 의존성을 설치합니다.  
  
##### 3단계: 내부 패키지로 코드 공유  
  
1.  `packages/core`와 같이 공유 코드를 담을 새 패키지(폴더)를 만듭니다.  
2.  \*\*루트 `pyproject.toml`\*\*에 이 패키지를 일반 의존성처럼 추가합니다.  
3.  \*\*루트 `pyproject.toml`\*\*에 `[tool.uv.sources]` 섹션을 추가하여, `core` 패키지를 PyPI가 아닌 워크스페이스 내부에서 찾도록 설정합니다.  
  
<!-- end list -->  
  
```toml  
[project]  
# 1. 내부 패키지를 의존성으로 추가  
dependencies = [  
    "core",  
    "python-dotenv"  
]  
  
# 2. 'core'가 로컬 워크스페이스 패키지임을 명시  
[tool.uv.sources]  
core = { workspace = true }  
```  
  
4.  `uv sync`를 다시 실행하면 `core` 패키지가 로컬 소스로 설치됩니다.  
5.  이제 `packages/api`나 `packages/cli`에서 `from core.news import ...` 구문으로 공통 코드를 불러올 수 있습니다.  
  
##### 4단계: 프로젝트 실행  
  
특정 프로젝트를 실행할 때는 `uv run --from <패키지명>`을 사용합니다.  
  
```bash  
# API 서버 실행  
uv run --from packages/api uvicorn main:app --reload  
  
# CLI 도구 실행  
uv run --from packages/cli python main.py  
```  
  
#### 3\. 사용 추천 대상  
  
  * 하나의 레포지토리에서 여러 개의 작은 자동화 스크립트, 웹훅, API, CLI 등을 관리할 때.  
  * 이 애플리케이션들이 공통의 로직이나 의존성을 공유할 때 매우 유용합니다.  
  * 반대로, 단일 스크립트나 PyPI에 독립적으로 배포할 패키지, 혹은 서로 완전히 관련 없는 앱들을 관리하는 데는 적합하지 않을 수 있습니다.  
  
-----  
  
**원본 영상 링크:** [https://www.youtube.com/watch?v=N\_ypJwV8Q8I](https://www.youtube.com/watch?v=N_ypJwV8Q8I)

## Comments



### Comment 46135

- Author: pcj9024
- Created: 2025-11-10T15:06:37+09:00
- Points: 1

pnpm과 상당히 유사하네요.