# UV Command Line Interface Documentation

Projects help manage Python code spanning multiple files. Working on projects is a core part of the uv experience. You can create a new Python project using the `uv init` command, which will create necessary files like `.python-version`, `README.md`, `hello.py`, and `pyproject.toml`. The `pyproject.toml` contains metadata about your project, including its name, version, description, and dependencies.

## Core Commands

### Project Management
- `uv init hello-world` - Create a new Python project named hello-world
- `uv init` - Initialize a project in the current working directory
- `uv build` - Build source and binary distributions for the project
- `uv run hello.py` - Run the hello.py script containing a simple 'Hello world' program

### Dependency Management
- `uv add requests` - Add the requests package as a dependency
- `uv remove requests` - Remove the requests package
- `uv lock --upgrade-package requests` - Upgrade requests to latest compatible version
- `uv sync` - Manually update the environment to match the lockfile
- `uv lock` - Create a lockfile for project dependencies

### Environment Management
- `uv venv` - Create a virtual environment
- `uv pip install <package>` - Install a package using pip
- `uv sync --extra build` - Sync build dependencies
- `uv sync --extra compile` - Sync compile dependencies

### Runtime Commands
- `uv run -- flask run -p 3000` - Run a Flask application on port 3000
- `uv run hello` - Run the 'hello' command defined in project scripts
- `uv run python -c "import example"` - Run Python commands in project environment
- `uv run example-cli foo` - Run project-provided example-cli command
- `uv run bash scripts/foo.sh` - Run bash scripts with project access
- `uv run --with httpx==0.26.0 python -c "import httpx; print(httpx.__version__)"` - Run with specific dependency versions

## Additional Commands
- `uv export` - Export lockfile to alternate format
- `uv tree` - Display dependency tree
- `uv tool` - Run commands provided by Python packages
- `uv python` - Manage Python versions and installations
- `uv pip` - Manage packages with pip interface
- `uv build` - Build source distributions and wheels
- `uv publish` - Upload distributions
- `uv cache` - Manage uv's cache
- `uv self` - Manage uv executable
- `uv version` - Display version
- `uv help` - Display command documentation

## Configuration Examples

### pyproject.toml Examples
```toml
# Python version requirement
requires-python = '>=3.12'

# Command line interface
[project.scripts]
hello = 'example:hello'

# Graphical user interface
[project.gui-scripts]
hello = 'example:app'

# Plugin registration
[project.entry-points.'example.plugins']
a = 'example_plugin_a'

# Environment configuration
[tool.uv]
environments = ['sys_platform == "darwin"', 'sys_platform == "linux"']
```

### Common Usage Examples
```bash
$ uv init my_project
$ uv run script.py
$ uv add requests
$ uv sync
$ uv lock
$ uv export requirements.txt
$ uv tree
$ uv tool run my_tool
$ uv python install 3.9
$ uv pip install requests
$ uv venv .venv
$ uv build .
$ uv publish dist/*
$ uv cache clean
$ uv self update
```
