The Modern Python Toolkit

Set Up Python
with uv

Transform your AI development workflow with the world's fastest Python package manager. One tool replaces them all — at 10 to 100× the speed.

Start Setup Why uv?
Scroll
Context

What uv Replaces

A single binary written in Rust that consolidates the fragmented Python toolchain into one fast, coherent experience.

 Old Way
python3 -m venv .venv source .venv/bin/activate python -m pip install --upgrade pip pip install -r requirements.txt pip freeze > requirements.txt
 With uv
uv init my-project uv add requests uv run main.py
No activation step. uv run automatically resolves and uses the project's virtual environment. You never type source activate again.
Step 1 of 6

Install uv

A single command, regardless of platform. Installs in under a second.

1
Install the uv binary
Choose your platform below
Shell 
# Install uv via the official installer
curl -LsSf https://astral.sh/uv/install.sh | sh
PowerShell 
# Install uv via PowerShell
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
Python 
# If you already have Python, you can also use pip
pip install uv
After installing, restart your terminal so the uv command is available on your PATH.
Verify installation
Confirm uv is ready
Shell 
uv --version
uv 0.x.x
Step 2 of 6

Initialize Your Project

One command creates the folder, sets up Git, writes a pyproject.toml, and generates a .gitignore.

2
Bootstrap the project
Replace my-project with your desired name
Shell 
uv init my-project
cd my-project
What uv init generated for you: a folder, git init, a .gitignore (Python-optimized), a README.md, and a modern pyproject.toml.

Now let's add a proper workspace structure:

Shell 
# Create a clean project skeleton
mkdir -p src scripts tests docs

Your project now looks like this:

my-project/
├── src/
├── scripts/
├── tests/
├── docs/
├──
├── pyproject.toml
├── README.md
└── hello.py
Step 3 of 6

Manage Python Versions

No system Python needed. uv downloads and manages isolated Python installations per-project — cleanly and silently.

3
Install a Python version
Pinned to this project only
Shell 
# Download and pin Python 3.12 for this project
uv python install 3.12

# Set it as the project's Python version
uv python pin 3.12
This does not change your system Python. The installation lives inside uv's managed directory. You can run uv python list to see all managed versions.

Verify it's active:

Shell 
uv run python --version
Python 3.12.x
Note the uv run prefix. That's all you need — no source .venv/bin/activate required. Ever.
Steps 4 & 5 of 6

Add Dependencies & Run Code

Installing packages is a single command. uv handles resolution, virtual environment creation, and lockfile generation automatically.

4
Install a package
Let's add requests as an example
Shell 
# Add a dependency — uv does everything else
uv add requests
Under the hood: uv created .venv/, resolved dependencies, installed the package, updated pyproject.toml, and generated a uv.lock file. All in under a second.

For dev-only tools (linters, formatters), use the --dev flag:

Shell 
# Dev dependencies don't ship with your project
uv add --dev ruff pytest
5
Write and run a script
Create scripts/hello.py
Python 
# scripts/hello.py
import requests

def main():
    response = requests.get("https://httpbin.org/get")
    print(f"Status: {response.status_code}")
    print(f"Python + uv works!")

if __name__ == "__main__":
    main()

Run it — no activation needed:

Shell 
uv run python scripts/hello.py
Status: 200
Python + uv works!
Step 6 of 6

Commit & Push

Your .gitignore already excludes .venv/ and Python caches. Just commit and ship.

6
Push to GitHub
Create a remote repo and push
Shell 
# Stage, commit, and push
git add .
git commit -m "Initial setup with uv"
git branch -M main
git remote add origin https://github.com/YOU/my-project.git
git push -u origin main
Always commit uv.lock — it guarantees that anyone who clones your repo gets exact same dependency versions, every time.
Completion

Final Checklist

Click each item as you complete it.