Python uv Quick Start: Build Your First Project

This guide takes the shortest path to get you a working Python project — your first usable environment with uv. Like adopting a first small otter: make sure it can eat and sleep first; advanced otter-petting techniques come later.

Prerequisites

• uv installed (see the install command in Overview)
• Terminal can run the uv command

Minimal Example: Create Your First Project

Step 1: Verify uv Is Installed

uv --version

If a version number appears, you're good to go. If not, run the install script again and restart your terminal.

Step 2: Initialize the Project

uv init my-app
cd my-app

uv automatically creates pyproject.toml, .python-version, main.py, and README.md. The structure looks roughly like:

my-app/
├── .gitignore
├── .python-version
├── README.md
├── main.py
└── pyproject.toml

Step 3: Run the Default Program

uv run main.py

You'll see Hello from my-app! — congratulations, your first project is alive.

Step 4: Add a Dependency and Run

uv add requests

Then update main.py to try it:

import requests
r = requests.get("https://httpbin.org/get")
print(r.status_code)

Run it:

uv run main.py

If you see 200, the dependency was correctly installed in the virtual environment — no manual pip install, no source .venv/bin/activate. That effortless feeling is the joy of uv.

Common Troubleshooting

Next Steps

Once the project runs, it's good to understand what pyproject.toml and uv.lock are doing. The next article covers these core concepts: 👉 Core Concepts