UV Project Management in Practice: A Complete Guide to Building Professional Python Projects from Scratch

Introduction: Common Pain Points in Python Project Management

Developers who are new to Python or frequently use AI Coding often encounter these frustrating problems:

• Chaotic dependency management: Projects won't run when switching to a different computer
• Import errors: Files are right next to each other, yet you get Module Not Found
• Unstable execution: Sometimes it runs, sometimes it doesn't
• Disorganized project structure: As files pile up, you don't know how to organize them

This article provides a simple yet professional Python project creation workflow—from tool selection to project structure to hands-on demonstration—to help you solve these problems once and for all.

Environment Setup: Why Choose UV as Your Python Project Management Tool

Essential Tool Checklist

Building a professional Python project requires three core tools:

1. Python: The newer the version, the better
2. UV: The next-generation Python project management tool
3. Git: The version control powerhouse

UV's Core Advantages

UV was released in 2024 by Astral (the same company behind the Python code formatter Ruff) and is written in Rust. Rust's memory safety guarantees and zero-cost abstractions enable UV to resolve dependencies 10–100x faster than traditional pip. UV fills a long-standing gap in the Python ecosystem—the lack of a unified project management tool. Previously, developers had to juggle pip (package installation), virtualenv (virtual environments), pip-tools (dependency locking), pyenv (Python version management), and other tools, resulting in severe toolchain fragmentation. UV draws inspiration from Cargo in the Rust ecosystem, consolidating all these capabilities into a single tool. It rapidly gained official recommendations from major open-source projects like FastAPI and Pydantic in the second half of 2024.

UV's advantages are primarily reflected in:

• Excellent version management: You can install and configure specific Python versions directly within a project, effortlessly resolving version conflicts between different projects
• Automatic virtual environment management: No need to manually create and activate venv. The essence of Python virtual environments is creating an isolated copy of the Python interpreter and an independent package installation directory in the file system. UV automatically detects and activates the corresponding virtual environment when executing uv run, completely eliminating the mental overhead of manually managing activation states—this is the fundamental solution to the "unstable execution" problem
• Intelligent dependency resolution: Automatically handles sub-dependency relationships
• All-in-one tool: Replaces the functionality of pip, virtualenv, pip-tools, and other tools

Goodbye requirements.txt: Modern Dependency Management with pyproject.toml

Problems with Traditional requirements.txt

The traditional requirements.txt has serious management deficiencies:

• Direct and transitive dependencies are all mixed together, making it difficult to clean up sub-dependencies when removing a package
• No distinction between development and production dependencies, causing users to install many unnecessary packages
• No locking mechanism, meaning installations at different times may produce different results

Advantages of pyproject.toml + uv.lock

pyproject.toml is not a UV-exclusive invention but a product of Python's official standardization process. It was first introduced by PEP 518 (2016) to declare build system dependencies; PEP 621 (2021) then further standardized the format for storing project metadata. This file uses the TOML (Tom's Obvious Minimal Language) format, which is more expressive than INI format and easier for humans to read and edit than JSON. The core design philosophy of pyproject.toml is "single source of truth"