1. Intro
Python으로 개발하면서 프로젝트의 의존성과 가상환경, 라이브러리를 활용하기 위해 다양한 방법으로 프로젝트를 설정해보았습니다. requirements.txt와 anaconda를 활용해보기도 하고, poetry를 활용하여 가상환경과 의존성을 관리해보기도 했는데요. 이밖에도 PDM, pip-sync 등 여러가지 라이브러리들이 있지만, 요즘 가장 핫한 uv를 활용해보는 방법을 적극 활용해보려고 합니다.
What is uv?
uv는 정말 빠른 Python 패키지 및 프로젝트 매니저라고 하며, Rust를 기반으로 만들어졌다고 합니다. 때문에 아래의 벤치마킹처럼 속도 역시 굉장히 빠르다고 하는데요. 개인적으로 uv를 사용하려는 가장 큰 이유는 완전한 PEP 지원이 이루어진다는 점이 가장 매력적이었던 것 같습니다.
uv는 PEP 517과 더불어 PEP 518, 508, 660을 지원하여 표준화된 패키지 관리와 빌드 시스템을 제공하며, 무엇보다 정말 빠릅니다...!
How to install?
uv는 아래의 방법으로 설치가 가능합니다.
# On macOS and Linux.
curl -LsSf https://astral.sh/uv/install.sh | sh
# On Windows.
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"
# With pip.
pip install uv
# With pipx.
pipx install uv
# With Homebrew.
brew install uv
# With Pacman.
pacman -S uv
Bash
복사
2. Simple usage of `uv`
python versions
uv 를 활용해서 원하는 python 버전을 설치해줄 수 있습니다. 아래와 같이 명령어를 사용하면 가장 latest로 배포된 python 버전을 설치하게 됩니다.
uv python install 3.10 3.11 3.12
# command results
# uv python install 3.10 3.11
# Installed 2 versions in 4.46s
# + cpython-3.10.15-macos-aarch64-none
# + cpython-3.11.10-macos-aarch64-none
Bash
복사
uv venv
uv를 활용하여 가상환경을 생성해줄 수 있습니다. 만약 원하는 버전이 있다면 --python 이라는 인자값을 넣어주고 가상환경 버전을 선택할 수 있습니다.
uv venv --python 3.12.0
# Using CPython 3.12.7
# Creating virtual environment at: .venv
# Activate with: source .venv/bin/activate
Bash
복사
설치된 버전을 확인하고 싶으면 아래와 같이 list를 확인할 수 있습니다.
uv python list
# cpython-3.13.0+freethreaded-macos-aarch64-none <download available>
# cpython-3.12.7-macos-aarch64-none /Users/goldstar/.local/share/uv/python/cpython-3.12.7-macos-aarch64-none/bin/python3.12
# cpython-3.12.4-macos-aarch64-none /opt/homebrew/opt/python@3.12/bin/python3.12 -> ../Frameworks/Python.framework/Versions/3.12/bin/python3.12
# cpython-3.11.10-macos-aarch64-none /opt/homebrew/opt/python@3.11/bin/python3.11 -> ../Frameworks/Python.framework/Versions/3.11/bin/python3.11
# ...
# pypy-3.8.16-macos-aarch64-none <download available>
Bash
복사
uv run
혹은 가상환경을 생성하진 않고 원하는 버전의 python console을 실행하고 싶을 때 아래와 같은 명령어를 사용해주면 됩니다. 만약 해당 버전의 python 혹은 pypy가 없다면 설치해주고 실행됩니다.
uv run --no-project --python pypy@3.8 -- python
Bash
복사
uv run --no-project --python pypy@3.8 -- python
Python 3.8.16 (a9dbdca6fc3286b0addd2240f11d97d8e8de187a, Dec 29 2022, 11:45:30)
[PyPy 7.3.11 with GCC Apple LLVM 13.1.6 (clang-1316.0.21.2.5)] on darwin
Type "help", "copyright", "credits" or "license" for more information.
>>>>
Bash
복사
uv init
파이썬 프로젝트를 생성하는 명령어로, 실행하게 되면 pyproject.toml 파일을 생성합니다. 함께 활용하는 명령어는 다음과 같습니다.
•
uv init: 새로운 파이썬 프로젝트를 생성함
•
uv add: 프로젝트의 종속성을 추가함
•
uv remove: 프로젝트의 종속성을 삭제함
•
uv sync: 프로젝트의 종속성을 환경과 동기화함
•
uv lock: 프로젝트의 종속성에 대한 잠금 파일을 생성함
•
uv run: 프로젝트 환경에서 명령어를 실행함
•
uv tree: 프로젝트의 종속성 트리를 확인할 수 있음
•
uv build: 프로젝트를 배포 아카이브로 빌드함
•
uv publish: 프로젝트를 패키지 인덱스에 게시함
3. Example
Create python project
uv를 활용하여 파이썬 프로젝트를 생성해줍니다.
uv init
Bash
복사
만약 error: Failed to discover parent workspace; 가 발생했다면 --no-workspace 옵션을 넣어주어 프로젝트를 생성해줍니다.
uv init --no-workspace
Bash
복사
버전을 선택하고 싶다면 --python 옵션으로 파이썬 버전을 선택할 수 있습니다.
uv init --no-workspace --python 3.12
TOML
복사
해당 명령어를 통해 pyproject.toml과 uv.lock등 여러 파일이 생성됨을 확인할 수 있습니다.
.
├── README.md
├── hello.py
├── pyproject.toml
└── uv.lock
Bash
복사
[project]
name = "[project-name]"
version = "0.1.0"
description = "Add your description here"
readme = "README.md"
requires-python = ">=3.12"
dependencies = []
TOML
복사
Add dependencies
간단하게 fastapi 라이브러리를 설치하여 실행해보도록 하겠습니다.
uv add fastapi --extra standard
Bash
복사
# Result
Using CPython 3.12.7
Creating virtual environment at: .venv
Resolved 10 packages in 36ms
Installed 9 packages in 11ms
+ annotated-types==0.7.0
+ anyio==4.6.2.post1
+ fastapi==0.115.4
+ idna==3.10
+ pydantic==2.9.2
+ pydantic-core==2.23.4
+ sniffio==1.3.1
+ starlette==0.41.2
+ typing-extensions==4.12.2
Bash
복사
그리고 lint를 해주기 위해 ruff 를 추가해주도록 합시다. 개발할 때만 사용하고 배포 시에는 활용하지 않을 것이므로 --dev에 추가해주도록 합시다.
uv add --dev ruff
Bash
복사
이 명령어까지 실행했다면 다음과 같이 pyproject.toml 파일이 추가됐을 것입니다. 여기서 fastapi 버전은 latest 업데이트 버전에 따라 달라질 수 있습니다.
[project]
name = "uv-test"
version = "0.1.0"
description = "Add your description here"
readme = "README.md"
requires-python = ">=3.12"
dependencies = [
"fastapi[standard]>=0.115.4",
]
[dependency-groups]
dev = [
"ruff>=0.7.3",
]
TOML
복사
FastAPI Quick-Start
먼저 main.py 이름으로 간단한 FastAPI 코드를 작성해줍니다.
from fastapi import FastAPI
app = FastAPI()
@app.get("/")
async def root():
return {"message": "Hello World"}
Python
복사
코드를 생성해줬다면 아래의 명령어로 fastapi를 실행해볼 수 있습니다.
uv run fastapi dev main.py
Bash
복사
INFO Using path main.py
INFO Resolved absolute path /Users/kkamikoon/Documents/DUMMY/uv-test/main.py
INFO Searching for package file structure from directories with __init__.py files
INFO Importing from /Users/kkamikoon/Documents/DUMMY/uv-test
╭─ Python module file ─╮
│ │
│ 🐍 main.py │
│ │
╰──────────────────────╯
INFO Importing module main
INFO Found importable FastAPI app
╭─ Importable FastAPI app ─╮
│ │
│ from main import app │
│ │
╰──────────────────────────╯
INFO Using import string main:app
╭────────── FastAPI CLI - Development mode ───────────╮
│ │
│ Serving at: http://127.0.0.1:8000 │
│ │
│ API docs: http://127.0.0.1:8000/docs │
│ │
│ Running in development mode, for production use: │
│ │
│ fastapi run │
│ │
╰─────────────────────────────────────────────────────╯
INFO: Will watch for changes in these directories: ['/Users/kkamikoon/Documents/DUMMY/uv-test']
INFO: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)
INFO: Started reloader process [32918] using WatchFiles
INFO: Started server process [32920]
INFO: Waiting for application startup.
INFO: Application startup complete.
Bash
복사
4. `uv` in PyCharm
PyCharm에서는 기본적으로 Virtualenv Environments, Anaconda, Poetry 등을 지원합니다. uv의 경우 uv add 혹은 uv venv 명령어로 생성된 .venv를 활용하여 개발환경과 싱크를 맞출 수 있습니다.
프로젝트 환경이 설정되지 않을 경우 import한 라이브러리 아래에 빨간줄이 뜨게 되는데 이를 해결하기 위해 아래의 Step을 따라하면 해결할 수 있습니다.
interpreter
만약 pyproject는 있지만 아직 venv가 없을 경우 아래의 명령어를 실행해줍니다. 해당 명령어를 실행하면 pyproject.toml 파일과 싱크를 맞춰 .venv 가상환경을 생성해줍니다.
uv sync
Bash
복사
이후 PyCharm 의 설정에서 아래와 같이 생성된 가상환경을 사용하도록 하게 되면 uv와 싱크를 맞춰 개발환경에 적용할 수 있습니다.
