Packages and uv

Python comes with built-in functions and a standard library, and you can write your own modules. But sometimes you need code that someone else has written and shared — an external package.

Where Code Comes From

Source	Example	How to use
Built-in	`print()`, `len()`, `int()`	Just use it
Standard library	`random`, `csv`, `json`	`import random`
Your own modules	`helpers.py`	`from helpers import load_data`
External packages	`openai`, `requests`	Install first, then import

External packages live on PyPI (the Python Package Index) — a public directory of thousands of packages anyone can download.

uv is a package manager that handles installing external packages and keeping track of what your project needs. It creates an isolated environment so each project has its own set of packages without conflicts.

The Three-Command Workflow

1. Initialize your project

uv init

This creates two things:

pyproject.toml — a file that tracks your project's dependencies
.venv/ — a virtual environment folder where packages get installed

You only run this once per project.

2. Add a package

uv add openai

This downloads the package from PyPI, installs it in your .venv/, and records it in pyproject.toml so anyone else can install the same dependencies.

3. Run your code

uv run python my_script.py

uv run makes sure Python uses the packages in your .venv/. Without it, Python won't find the packages you installed.

Example: Using the `openai` Package

After running uv init and uv add openai:

from openai import OpenAI

client = OpenAI()

response = client.chat.completions.create(
    model="gpt-4o-mini",
    messages=[
        {"role": "user", "content": "What is Python?"}
    ]
)

print(response.choices[0].message.content)

uv run python my_script.py

What `pyproject.toml` Looks Like

After uv init and uv add openai, your pyproject.toml will include something like:

[project]
name = "my-project"
version = "0.1.0"
dependencies = [
    "openai",
]

This file is how your project remembers what it needs. When someone else clones your project, they can install everything with:

uv sync

Adding More Packages

uv add requests
uv add rich

Each uv add installs the package and updates pyproject.toml.

Common Mistakes

Running python instead of uv run python

# Wrong — Python can't find installed packages
python my_script.py

# Right — uv activates the environment for you
uv run python my_script.py

Forgetting to run uv init first

# Wrong — no project set up yet
uv add openai  # Error!

# Right — initialize, then add
uv init
uv add openai

Installing packages globally instead of per-project

# Wrong — installs system-wide, can cause conflicts
pip install openai

# Right — keeps packages in this project's .venv
uv add openai

Forgetting to commit pyproject.toml

Your pyproject.toml should be committed to Git so collaborators can install the same packages. The .venv/ folder should not be committed — add it to .gitignore.