UV Python Package Manager: The Essentials

UV Python Package Manager: The Essentials

I just get rid of Conda and switch to uv.

TL;DR

uv init prj_51 --python 3.12
cd prj_51
code .
uv add numpy
# write code...
uv run main.py

# Out of VScode - Option I
uv run main.py

# Out of VScode - Option II
Set-Env . # or .venv\Scripts\activate
python main.py

• I use Windows 11 and VSCode
• Read the doc

Install

winget install astral-sh.uv
uv --version

PowerShell function for quick activation

Add this function to your Documents/PowerShell/Microsoft.PowerShell_profile.ps1 profile:

# Function to activate a venv
function Set-Env {
    param([string]$EnvName = $null)
    
    # If argument is "." or no argument provided
    if (($EnvName -eq ".") -or (-not $EnvName)) {
        # Case 1: uv project with .venv
        if (Test-Path ".\.venv\Scripts\Activate.ps1") {
            & ".\.venv\Scripts\Activate.ps1"
            return
        }
        # Case 2: Inside a folder that IS the environment (uv venv myproj then cd myproj)
        if (Test-Path ".\Scripts\Activate.ps1") {
            & ".\Scripts\Activate.ps1"
            return
        }
        # Case 3: Environment in parent folder (uv venv myproj from parent)
        $parentName = Split-Path -Leaf (Get-Location)
        if (Test-Path "..\$parentName\Scripts\Activate.ps1") {
            & "..\$parentName\Scripts\Activate.ps1"
            return
        }
        # Otherwise search for "venv" by default
        $EnvName = "venv"
    }
    
    # Search for named environment in current directory
    if (Test-Path ".\$EnvName\Scripts\Activate.ps1") {
        & ".\$EnvName\Scripts\Activate.ps1"
    }
    # Search for named environment in parent directory
    elseif (Test-Path "..\$EnvName\Scripts\Activate.ps1") {
        & "..\$EnvName\Scripts\Activate.ps1"
    }
    else {
        Write-Host "Environment '$EnvName' not found" -ForegroundColor Red
    }
}

Episode IV: A New Hope

uv init prj_51
cd prj_51
code .

CTRL + ù

uv run main.py

A .venv is created

uv add numpy

Now pyproject.toml looks like this:

[project]
name = "prj-51"
version = "0.1.0"
description = "Add your description here"
readme = "README.md"
requires-python = ">=3.14"
dependencies = [
    "numpy>=2.3.4",
]

And the code looks like that:

# main.py

import numpy as np

def main():
    # Create a simple 2D NumPy array
    # (Think of it as a small matrix)
    arr = np.array([[1, 2, 3],
                    [4, 5, 6]])

    # Print the array
    print("Hello NumPy!")
    print("Here is your array:")
    print(arr)

    # Compute and print the sum of all elements
    print("Sum of all elements:", np.sum(arr))

    # Compute the mean (average) value
    print("Mean value:", np.mean(arr))


if __name__ == "__main__":
    main()

In VSCode console

uv run main.py

Let’s leave VSCode and let’s go back in Powershell

uv run main.py

Now, if you don’t want to use uv run main.py but you prefer to call python main.py the .env must be activated manually.

.venv\Scripts\activate
python main.py

Let’s deactivate the environment (just for the next test)

deactivate

Let’s reactivate .env manually with our Set-Env function

Set-Env .
python main.py

There is a smell of rust in the air…

uv was created by the same team that made Ruff, and they clearly drew inspiration from the Rust ecosystem:

Rust (Cargo)	Python (uv)
cargo new	uv init
cargo add	uv add
Cargo.toml	pyproject.toml
Cargo.lock	uv.lock
cargo build	uv build
cargo run	uv run

Why this inspiration?

The Rust ecosystem is renowned for having one of the best package manager among modern languages. Python has needed this for a long time!

Before uv, we had:

• pip (installer)
• venv (virtual environments)
• setuptools / poetry / pipenv (project management)
• pyenv (Python versions)

uv unifies all of this into a single fast tool with the same philosophy as Cargo.

The difference

Unlike Rust, where Cargo is the official tool, uv is a third-party tool that aims to modernize the Python ecosystem.

VSCode setup

Optional because VSCode may ask you the question when the project is loaded.

1. Open a Python project in VSCode
2. Press Ctrl+Shift+P → “Python: Select Interpreter”
3. Choose the interpreter inside the .\Scripts\python.exe folder