> Source URL: /resources/packages.guide
# 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.

## What Is `uv`?

`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

```bash
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

```bash
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

```bash
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`:

```python
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)
```

```bash
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:

```toml
[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:

```bash
uv sync
```

## Adding More Packages

```bash
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`**

```bash
# 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**

```bash
# 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**

```bash
# 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`.


---

## Backlinks

The following sources link to this document:

- [Packages and uv Guide](/resources/resources.index.llm.md)
- [Packages and uv Guide](/resources/modules.guide.llm.md)