Getting Started with uv: Setting Up Your Python Project in 2025

Python’s ecosystem has long been a powerhouse for developers, but managing dependencies, virtual environments, and Python versions has often felt clunky with traditional tools like pip and venv. Enter uv, a next-generation Python package and project manager written in Rust by the Astral team (known for the popular ruff linter).

Launched in February 2024, uv has rapidly gained traction for its speed (10-100x faster than pip), seamless integration with existing workflows, and all-in-one approach to Python project management. In this article, we’ll walk through how to start using uv and set up a Python project from scratch, leveraging the latest features as of March 2025.

What is uv?

uv is an all-in-one Python tool designed to replace a patchwork of utilities like pip (package installer), venv (virtual environment manager), and even poetry (project manager). Built in Rust, it boasts performance that’s 10-100x faster than traditional tools, thanks to its optimized dependency resolver and aggressive caching strategy. It’s not just a package installer—it’s a full-fledged project manager that handles Python versions, virtual environments, dependencies, and script execution with ease.

Key features of uv include:

• Speed: Installs packages and resolves dependencies in seconds, not minutes.
• Unified Workflow: Combines environment creation, package management, and script running into one tool.
• Standards Compliance: Uses the standard pyproject.toml for configuration and a cross-platform uv.lock file for reproducible builds.
• No Manual Activation: Automatically manages virtual environments without requiring you to activate them manually.

As of March 2025, uv has matured significantly since its initial release, with stable support for project management, Python version handling, and seamless integration into existing workflows. Let’s see how to set it up.

Setting Up Your Python Project with uv

In this section we are going to set up a Python project using uv. We are going to install uv and create a new project.

Step 1: Installing uv

To use uv, you first need to install it. Unlike many Python tools, uv doesn’t require a pre-existing Python installation because it can manage Python versions itself. However, it’s recommended to install it directly rather than via pip to avoid dependency conflicts with your system Python. Here’s how to install the latest version (as of March 2025, version 0.6.5 is available on PyPI, but always check astral.sh for updates):

On macOS/Linux

Open your terminal and run:

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

This downloads and installs uv as a standalone binary.

Log:

downloading uv 0.6.6 aarch64-apple-darwin
no checksums to verify
installing to /Users/user/.local/bin
  uv
  uvx
everything's installed!

To add $HOME/.local/bin to your PATH, either restart your shell or run:

    source $HOME/.local/bin/env (sh, bash, zsh)
    source $HOME/.local/bin/env.fish (fish)
WARNING: The following commands are shadowed by other commands in your PATH: uv uvx

On Windows

Using PowerShell:

irm https://astral.sh/uv/install.ps1 | iex

Verify Installation

After installation, confirm it worked by checking the version:

uv --version

You should see something like uv 0.6.6. If not, ensure uv is added to your system PATH (the installer usually handles this, but you might need to restart your terminal).

Log:

╰─❯ uv --version
uv 0.6.6 (c1a0bb85e 2025-03-12)

Step 2: Initializing a New Project

With uv installed, let’s create a new Python project. uv makes this a breeze with the uv init command, which sets up a basic project structure.

1. Create a Project Directory:

   Navigate to where you want your project and run:

   uv init my-python-project
   cd my-python-project

   This sets up a minimal project structure tailored for quick starts. As of March 2025, running uv init generates the following files and directories in your project root:

   my-python-project/
   ├── .python-version  # Specifies the pinned Python version (e.g., "3.12")
   ├── main.py         # A simple starter Python script
   ├── pyproject.toml  # Project configuration file
   └── README.md       # Basic project documentation (empty by default)

   Note: Depending on your setup, you might also see hidden directories like .git (if you initialize a Git repository) or .ropeproject (if you’re using an IDE like PyCharm with Rope for refactoring). These are not created by uv itself but may appear based on your environment or subsequent actions.

   The pyproject.toml file is the core of your project, following the PEP 621 standard. It looks something like this:

   [project]
   name = "my-python-project"
   version = "0.1.0"
   description = "Add your description here"
   readme = "README.md"
   requires-python = ">=3.13"
   dependencies = []

   The main.py file comes with a basic “Hello, World!” example:

       def main():
     print("Hello from my-python-project!")
   
   
     if __name__ == "__main__":
     main()
   

   The .python-version file pins the Python version (e.g., 3.13), and README.md starts as an empty file ready for your project description.

   2. Set a Python Version (Optional) The .python-version file is created automatically by uv init, typically defaulting to the latest Python version available on your system (e.g., 3.12). To change it to a specific version:

      uv python pin 3.12

      This updates .python-version and ensures consistency across machines. Be sure to update the requires-python = ">=3.12" before in pyproject.toml.

Step 3: Setting Up a Virtual Environment

With traditional tools, you’d manually create a virtual environment using python -m venv. uv simplifies this with the uv venv command, automatically placing it in a .venv folder in your project root.

Run:

uv venv

You’ll see output like:

Using Python 3.12.7
Creating virtual environment at: .venv
Activate with: source .venv/bin/activate

To activate it:

• macOS/Linux: source .venv/bin/activate
• Windows: .venv\Scripts\activate

However, uv often eliminates the need to manually activate environments by handling this automatically with commands like uv run (more on that later).

Step 4: Adding Dependencies

Now, let’s add some packages to your project. uv manages dependencies via pyproject.toml, and you can add them interactively or manually.

Interactive Method

To add requests (a popular HTTP library):

uv add requests

This updates pyproject.toml with:

[project]
dependencies = [
    "requests>=2.32.3",
]

It also creates a uv.lock file, a cross-platform lockfile ensuring reproducible builds by pinning exact versions.

Manual Method

Add the packages to pyproject.toml

Edit pyproject.toml directly. For example:

[project]
name = "my-python-project"
version = "0.1.0"
requires-python = ">=3.12"
dependencies = [
    "fastapi>=0.115.6",
    "pandas>=2.2.1",
]
[dependency-groups]
dev = ["pytest>=8.3.4"]

Here, fastapi and pandas are production dependencies, while pytest is a development dependency.

Installing Dependencies

To install all dependencies (including dev ones) into your virtual environment:

uv sync

❯ uv sync
Resolved 25 packages in 1.37s
Prepared 18 packages in 3.28s
Installed 18 packages in 51ms
 + annotated-types==0.7.0
 + anyio==4.8.0
 + fastapi==0.115.11
 + iniconfig==2.0.0
 + numpy==2.2.3
 + packaging==24.2
 + pandas==2.2.3
 + pluggy==1.5.0
 + pydantic==2.10.6
 + pydantic-core==2.27.2
 + pytest==8.3.5
 + python-dateutil==2.9.0.post0
 + pytz==2025.1
 + six==1.17.0
 + sniffio==1.3.1
 + starlette==0.46.1
 + typing-extensions==4.12.2
 + tzdata==2025.1

This reads pyproject.toml, resolves dependencies, and installs them into .venv. If you only want production dependencies, use:

uv sync --no-dev

The speed of uv sync is remarkable—often completing in milliseconds compared to minutes with pip.

Step 5: Writing and Running Code

Let’s create a simple script. In my_python_project/main.py, add:

import requests

def fetch_data():
    response = requests.get("https://api.github.com")
    print(response.json())

if __name__ == "__main__":
    fetch_data()

To run it, use:

uv run python main.py

uv run ensures the script runs in the project’s virtual environment, installing dependencies if needed. You can also run it directly:

uv run main.py

Step 6: Managing Your Project

As your project grows, uv offers tools to keep it organized.

• Update Dependencies To upgrade packages to their latest compatible versions:

  uv sync --upgrade

• Export to requirements.txt If you need a traditional requirements.txt:

  uv export --format requirements-txt > requirements.txt

• Run Commands Execute any command in the project environment:

  uv run pytest

Step 7: Managing Python Versions

List installed Python versions:

uv python list

Install a specific version:

uv python install 3.11

Step 8: Removing Packages with uv

As your project evolves, you might need to remove a package that’s no longer needed. With uv, uninstalling dependencies is just as straightforward as adding them, and it keeps your project configuration and environment in sync.

1. Remove a Package Suppose you added requests earlier but no longer need it. To remove it:

   uv remove requests

   This command:

   • Deletes requests from the [project.dependencies] section in your pyproject.toml.
   • Uninstalls the package from the virtual environment (.venv).
   • Updates the uv.lock file to reflect the change, ensuring reproducibility.

   For example, if your pyproject.toml originally had:

   [project]
   name = "my-python-project"
   version = "0.1.0"
   description = "A new Python project"
   requires-python = ">=3.12"
   dependencies = [
       "requests>=2.31.0",
   ]

   After running uv remove requests, it becomes:

   [project]
   name = "my-python-project"
   version = "0.1.0"
   description = "A new Python project"
   requires-python = ">=3.12"
   dependencies = []

2. Remove a Development Dependency If you installed a development dependency like pytest with uv add --dev pytest and want to remove it:

   uv remove --dev pytest

   This targets the [dependency-groups.dev] section in pyproject.toml and removes pytest from both the configuration and the virtual environment.

3. Sync the Environment (Optional) While uv remove typically updates the environment automatically, you can ensure everything is consistent by running:

   uv sync

   This reconciles the virtual environment with the updated pyproject.toml and uv.lock, removing any orphaned packages.

4. Manual Removal (Not Recommended) If you manually edit pyproject.toml to remove a dependency (e.g., deleting requests from the dependencies list), uv won’t automatically uninstall it from .venv until you run uv sync. Stick to uv remove to avoid this extra step and keep your project clean.

Why Choose uv in 2025?

By March 2025, uv has solidified its place as a game-changer in Python development. Its speed alone—often installing dependencies 10-20x faster than pip—is a compelling reason to switch. Add to that its seamless integration with modern standards (pyproject.toml, uv.lock), automatic Python version management, and a streamlined workflow, and it’s clear why developers, including the FastAPI team, have adopted it.

For beginners, uv reduces the complexity of managing Python environments. For pros, it saves time and ensures reproducibility. Whether you’re building a small script or a large application, uv adapts to your needs.

What’s Next?

Now that you’ve mastered the basics of uv project management, you might want to explore more advanced capabilities:

• Script Execution: Learn how to run standalone Python scripts without creating full projects in our guide Running Test Scripts with uv: No Dependencies Management Required
• Text-to-Speech: Build a powerful audio generation script with Text-to-Speech with uv: Create Audio from Text in Python
• Deployment: See how to deploy uv projects in our article Deploying a Python uv Project with Git and Railpack in Dokploy

Conclusion

uv is a game-changer for Python developers in 2025, offering a fast, unified, and intuitive way to manage projects. From installation to dependency management, it reduces friction and lets you focus on coding. To stay updated, check the official documentation at docs.astral.sh/uv or the GitHub repo at github.com/astral-sh/uv.

Ready to try it? Install uv, initialize a project, and experience Python development at warp speed. Happy coding!