Python Project Management: Poetry, uv, and Rye

Managing Python projects beyond simple scripts requires robust tooling for dependencies, virtual environments, and packaging. For years, pip and virtualenv were the standard, but modern projects demand more: reproducible builds, lock files, and seamless collaboration. Enter Poetry, uv, and Rye—three tools that revolutionize Python project management. Poetry offers a complete solution with dependency resolution, packaging, and publishing. uv, built in Rust, focuses on blistering speed for installation and resolution. Rye provides a holistic approach, managing Python versions and project scaffolding. This tutorial dives deep into each tool, comparing their strengths and weaknesses, and shows you how to integrate them into your workflow. Whether you're building a library, a web app, or a data pipeline, mastering these tools will save you time and prevent dependency hell.

Getting Started with Poetry

Poetry is a dependency manager and packaging tool that simplifies project setup. Install it via the official installer: curl -sSL https://install.python-poetry.org | python3 -. Initialize a new project with poetry new my-project or add Poetry to an existing project with poetry init. Poetry creates a pyproject.toml file where you define dependencies. For example, to add requests: poetry add requests. This updates pyproject.toml and generates a poetry.lock file for reproducible installs. Poetry also manages virtual environments automatically. Use poetry shell to activate the environment or poetry run python script.py to run a script within it. For production, use poetry install --no-dev to exclude development dependencies.

# Example project structure after poetry new
# my-project/
# ├── pyproject.toml
# ├── README.rst
# ├── my_project
# │   └── __init__.py
# └── tests
#     └── __init__.py

# pyproject.toml content
[tool.poetry]
name = "my-project"
version = "0.1.0"
description = ""
authors = ["Your Name <you@example.com>"]

[tool.poetry.dependencies]
python = "^3.9"
requests = "^2.28"

[tool.poetry.dev-dependencies]
pytest = "^7.0"

[build-system]
requires = ["poetry-core"]
build-backend = "poetry.core.masonry.api"

Supercharging with uv

uv is a fast Python package installer and resolver written in Rust. It's designed as a drop-in replacement for pip and pip-tools, but also works with Poetry projects. Install uv via curl -LsSf https://astral.sh/uv/install.sh | sh. Basic usage: uv pip install requests installs packages similarly to pip. For project management, uv can read pyproject.toml and generate a lock file with uv lock. Use uv sync to install dependencies from the lock file. uv is significantly faster than pip, often 10-100x faster in resolution. It also supports virtual environments: uv venv creates a .venv folder. uv can be used alongside Poetry: you can use uv pip install for ad-hoc packages while Poetry manages the project. For CI/CD, uv's speed reduces build times dramatically.

# Install uv
curl -LsSf https://astral.sh/uv/install.sh | sh

# Create a virtual environment
uv venv

# Activate (on Unix)
source .venv/bin/activate

# Install packages
uv pip install requests pytest

# Generate lock file from pyproject.toml
uv lock

# Sync environment from lock file
uv sync

# Run a script
uv run python script.py

Rye: The All-in-One Project Manager

Rye is a project manager that handles Python version management, virtual environments, and dependencies. It's built on top of uv for speed. Install Rye via curl -sSf https://rye-up.com/install | bash. Initialize a project with rye init my-project. This creates a pyproject.toml and a .python-version file. Rye automatically downloads and manages Python versions using rye pin to set a specific version. Add dependencies with rye add requests. Rye uses a requirements.lock file for reproducible builds. It also supports workspaces for monorepos. Rye's rye sync command installs dependencies and sets up the virtual environment. For running scripts, use rye run python script.py. Rye integrates well with IDEs and CI systems.

# Install Rye
curl -sSf https://rye-up.com/install | bash

# Initialize a new project
rye init my-project
cd my-project

# Pin Python version
rye pin 3.11

# Add dependencies
rye add requests
rye add --dev pytest

# Sync environment
rye sync

# Run a script
rye run python script.py

# Generate lock file (automatically done on sync)
cat requirements.lock

Comparing Dependency Resolution Strategies

Dependency resolution is critical for avoiding conflicts. Poetry uses a SAT solver for deterministic resolution, ensuring that the same pyproject.toml always produces the same lock file. uv uses a backtracking resolver optimized for speed, often finding solutions faster than pip. Rye leverages uv's resolver under the hood. All three produce lock files, but they differ in format: Poetry uses poetry.lock (TOML), uv uses uv.lock (TOML), and Rye uses requirements.lock (pip-compatible). For most projects, the choice depends on speed vs. ecosystem compatibility. Poetry's resolver is more conservative, while uv's is aggressive but fast. In practice, uv's resolver rarely misses valid solutions. For monorepos, Rye's workspace support is a standout feature.

# Example pyproject.toml with conflicting dependencies
[tool.poetry.dependencies]
python = "^3.9"
numpy = ">=1.20"
tensorflow = ">=2.8"
# tensorflow requires numpy<1.24, so conflict

# Poetry resolution:
# poetry add tensorflow
# -> SolverError: Because tensorflow (2.8) depends on numpy (>=1.14.5,<1.24)
#    and numpy (>=1.20) is incompatible, no solution.

# uv resolution:
# uv add tensorflow
# -> error: No solution found for numpy

# Both fail, but uv is faster.

Publishing Packages with Poetry and uv

Publishing Python packages to PyPI is streamlined with Poetry and uv. For Poetry, configure credentials with poetry config pypi-token.pypi <token>. Build the package with poetry build, which creates source and wheel distributions in the dist/ folder. Publish with poetry publish. uv also supports building and publishing: uv build and uv publish. Both tools handle versioning automatically from pyproject.toml. For private repositories, configure sources in pyproject.toml under [[tool.poetry.source]] or [tool.uv.sources]. Rye currently focuses on project management and does not have built-in publishing, but you can use rye build and then twine upload.

# Poetry publish
poetry build
poetry publish

# uv publish (requires uv >=0.2.0)
uv build
uv publish

# For private index
# pyproject.toml for Poetry
[[tool.poetry.source]]
name = "private"
url = "https://private-pypi.example.com/simple/"
default = true

# For uv
[tool.uv.sources]
private = { index = "https://private-pypi.example.com/simple/" }

Migrating from pip/requirements.txt to Modern Tools

Migrating an existing project to Poetry, uv, or Rye is straightforward. For Poetry, run poetry init and answer the prompts. It will parse existing requirements.txt if present. Alternatively, use poetry add $(cat requirements.txt) to add all dependencies. For uv, you can use uv pip install -r requirements.txt initially, then generate a lock file with uv lock. Rye's rye init can import from requirements.txt as well. After migration, commit the lock file and remove requirements.txt to avoid confusion. For large projects, test the migration in a branch and verify that tests pass.

# Migrate to Poetry
cd existing-project
poetry init  # follow prompts, it will detect requirements.txt
poetry add $(cat requirements.txt)  # alternative
poetry install

# Migrate to uv
uv pip install -r requirements.txt
uv lock

# Migrate to Rye
rye init
rye add $(cat requirements.txt)
rye sync

Workspaces and Monorepos with Rye

Rye supports workspaces, allowing you to manage multiple packages in a single repository. Define workspaces in pyproject.toml under [tool.rye.workspace] with members = ["packages/*"]. Each member package has its own pyproject.toml. Rye syncs all dependencies across the workspace, ensuring consistent versions. This is ideal for microservices or shared libraries. Poetry also supports workspaces via [tool.poetry.workspace], but it's less mature. uv does not have native workspace support yet. Rye's workspace feature simplifies dependency management in monorepos.

# Project structure
# monorepo/
# ├── pyproject.toml
# ├── packages/
# │   ├── lib-a/
# │   │   └── pyproject.toml
# │   └── lib-b/
# │       └── pyproject.toml
# └── .python-version

# Root pyproject.toml
[tool.rye.workspace]
members = ["packages/*"]

# Initialize workspace
rye init monorepo
cd monorepo
rye init packages/lib-a
rye init packages/lib-b

# Add inter-package dependency
cd packages/lib-b
rye add lib-a --path ../lib-a

# Sync all
rye sync