> ## Documentation Index
> Fetch the complete documentation index at: https://fastapi2day.codewithsiva.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Creating and Managing Python Projects with uv

> Use uv to initialize a Python project, add packages, understand pyproject.toml and lock files, and run your scripts the modern way.

Now that you know why `uv` is worth using, let's actually build something with it. This page walks you through creating a project from scratch, adding dependencies, understanding the files `uv` generates, and the different ways to run your code. By the end you'll have a complete mental model for how `uv` manages your project's environment, and you'll be comfortable reaching for it on every new project you start.

## Creating a new project

```bash theme={null}
uv init ai-assistant
cd ai-assistant
```

`uv init` creates a complete project scaffold:

```text theme={null}
ai-assistant/
├── .gitignore       # Git ignores .venv, .env, __pycache__, etc.
├── .python-version  # Pins the Python version for this project
├── pyproject.toml   # Project configuration and dependencies
├── README.md        # Project description
└── main.py          # Example entry-point script
```

<Note>
  The `.venv` folder and `uv.lock` file are created automatically the first time you run `uv add` to install a package — not at `uv init` time.
</Note>

## Understanding pyproject.toml

This single file replaces `requirements.txt`, `setup.py`, `setup.cfg`, and other scattered configuration:

```toml theme={null}
[project]
name = "ai-assistant"
version = "0.1.0"
description = "Add your description here"
readme = "README.md"
requires-python = ">=3.12"
dependencies = []
```

Every package you add with `uv add` gets recorded here automatically.

## Adding packages

```bash theme={null}
# Add a single package
uv add requests

# Add several at once
uv add pandas numpy matplotlib

# Add development-only dependencies
uv add --dev pytest black
```

After adding packages, `pyproject.toml` updates itself:

```toml theme={null}
[project]
name = "ai-assistant"
version = "0.1.0"
description = "Add your description here"
readme = "README.md"
requires-python = ">=3.12"
dependencies = [
    "requests>=2.32.0",
    "pandas>=2.2.0",
    "numpy>=1.26.0",
    "matplotlib>=3.8.0",
]

[tool.uv]
dev-dependencies = [
    "pytest>=8.0.0",
    "black>=24.0.0",
]
```

## The lock file

`uv` creates `uv.lock` alongside your `pyproject.toml`. This file records the exact version of every package (including transitive dependencies) so that anyone who clones your project and runs `uv sync` gets an identical environment:

```toml theme={null}
# uv.lock (auto-generated — commit this file)
version = 1
requires-python = ">=3.12"

[[package]]
name = "requests"
version = "2.32.3"
dependencies = [
    { name = "certifi" },
    { name = "charset-normalizer" },
]
```

<Tip>
  Commit `uv.lock` to Git. It's what guarantees reproducible builds across your machine, a teammate's machine, and any CI/CD environment.
</Tip>

## Running your code

```bash theme={null}
# Recommended — uv always uses the correct Python for the project
uv run python main.py

# Traditional — activate first, then run normally
source .venv/bin/activate   # macOS/Linux
.venv\Scripts\activate      # Windows
python main.py

# Direct path — no activation needed
.venv/bin/python main.py    # macOS/Linux
```

`uv run` is the recommended approach because it automatically uses the project's virtual environment without any activation step.

## Common uv commands

```bash theme={null}
# Project management
uv init project-name        # Create a new project
uv add package-name         # Add a package
uv remove package-name      # Remove a package
uv sync                     # Install all dependencies from uv.lock
uv add --upgrade pkg-name   # Upgrade a specific package

# Running code
uv run python script.py     # Run a script in the project's environment
uv pip list                 # List installed packages
```

## Working with existing projects

If you have a project using the old `requirements.txt` approach, uv can work with it immediately:

```bash theme={null}
# Install from an existing requirements file
uv pip install -r requirements.txt

# Or migrate by adding all existing requirements to pyproject.toml
uv add -r requirements.txt
```

## Virtual environment details

`uv` creates `.venv` automatically inside your project directory when you first add a package. Key things to know:

* No manual activation is needed when you use `uv run`
* VS Code detects `.venv` automatically and uses it for IntelliSense and the integrated terminal
* `.venv` is already in the `.gitignore` that `uv init` creates — don't commit it

## Tips and tricks

**Install global tools** (available system-wide, not per-project):

```bash theme={null}
uv tool install black
uv tool install mypy
```

**Manage Python versions** without pyenv:

```bash theme={null}
uv python install 3.12
uv python install 3.11
```

**Add custom run scripts** to `pyproject.toml`:

```toml theme={null}
[project.scripts]
start = "ai_assistant.main:run"
```

## What's next?

Ready to put the whole workflow together from start to finish?

<Card title="Complete setup" icon="circle-check" href="/weather-project/complete-setup">
  Start-to-finish project creation guide
</Card>