---
name: package
description: "uv package guide for Python projects using Astral's package, project, tool, and Python management workflows"
metadata:
  languages: "python"
  versions: "0.10.9"
  revision: 1
  updated-on: "2026-03-12"
  source: maintainer
  tags: "uv,python,packaging,virtualenv,dependency-management,cli"
---

# uv Python Package Guide

## Golden Rule

Use `uv` as the entry point for Python environment, dependency, script, tool, and interpreter management instead of mixing ad hoc `pip`, `venv`, `pip-tools`, `pipx`, and `pyenv` workflows inside the same project. For a managed project, keep dependencies in `pyproject.toml`, let `uv lock` and `uv sync` own the environment state, and treat private indexes as an explicit configuration and authentication step.

## Install

The maintainer docs prefer the standalone installer or an OS package manager for end-user CLI installs. Installing from PyPI is still valid when you need `uv` inside an existing Python environment.

```bash
curl -LsSf https://astral.sh/uv/install.sh | sh
```

```bash
python -m pip install "uv==0.10.9"
```

Common alternatives:

```bash
brew install uv
winget install --id=astral-sh.uv -e
```

Check the installed version:

```bash
uv --version
```

## Initialize And Manage A Project

Create a new project:

```bash
uv init my-app
cd my-app
```

Add dependencies and run code through the managed environment:

```bash
uv add httpx
uv run python -c "import httpx; print(httpx.__version__)"
```

Important project files:

- `pyproject.toml`: project metadata, dependencies, and `tool.uv` settings
- `uv.lock`: lockfile generated by `uv lock`
- `.venv/`: project virtual environment created and updated by `uv sync` and `uv run`

`uv run ...` will create the project virtual environment if needed before running the command. `uv sync` installs the lockfile state into the environment, and it is exact by default, so packages not declared in the lockfile are removed unless you opt into `--inexact`.

## Core Workflows

### Add, remove, lock, and sync dependencies

```bash
uv add pydantic
uv remove pydantic
uv lock
uv sync
```

Use `uv lock --check` in CI when you want to fail on lock drift instead of rewriting the lockfile.

### Run a single script with inline metadata

For one-file scripts, `uv` supports inline script metadata and can manage script dependencies directly:

```bash
uv add --script main.py httpx
uv run main.py
```

This is useful when the repo does not need a full project layout but still needs reproducible dependencies.

### Use the pip-compatible interface when a project is not uv-managed

`uv` also exposes a `pip`-compatible surface:

```bash
uv venv
uv pip install ruff
uv pip freeze
```

Prefer the project commands (`uv add`, `uv lock`, `uv sync`, `uv run`) for applications with a `pyproject.toml`. Reach for `uv pip ...` when you explicitly need pip-style behavior or are operating on an environment that is not managed through uv's project model. By default, `uv pip` expects a virtual environment, so create one first with `uv venv` or activate an existing environment.

### Install and run developer tools

For global or user-level CLI tools, use the tool workflow instead of adding those packages to your app dependencies:

```bash
uv tool install ruff
uv tool run ruff check .
uvx pycowsay "hello"
```

`uvx` is an alias for `uv tool run` and is the fast path for one-off tool execution.

### Manage Python interpreters

`uv` can install and select Python versions directly:

```bash
uv python install 3.12
uv python pin 3.12
```

This is useful when bootstrapping a project on a machine without the expected interpreter already available.

## Configuration And Auth

Project-level configuration usually lives in `pyproject.toml` under `[tool.uv]`. A sibling `uv.toml` file is also supported and takes precedence over `[tool.uv]` when both exist.

Example project settings:

```toml
[tool.uv]
managed = true

[[tool.uv.index]]
name = "internal"
url = "https://packages.example.com/simple"

[tool.uv.sources]
my-lib = { index = "internal" }
```

Use `[[tool.uv.index]]` to define alternative or private package indexes. If you want an index to replace PyPI as the default, set `default = true` on that index.

For credentials, prefer external auth instead of embedding secrets in `pyproject.toml`:

- HTTP credentials can be supplied in the URL, though that is usually the least safe option
- `uv` can read credentials from `.netrc`
- `uv` supports a keyring subprocess provider
- Native secret-store auth exists behind the preview feature `native-auth`

For index-specific environment variables, derive the variable name from the index name:

```bash
export UV_INDEX_INTERNAL_USERNAME="scott"
export UV_INDEX_INTERNAL_PASSWORD="tiger"
```

When using private indexes, verify both pieces separately:

1. The index configuration is correct.
2. Authentication is available in the environment where `uv` runs.

## Common Pitfalls

- Do not mix `uv add` and manual `pip install` into the same managed `.venv` and assume the lockfile still reflects reality.
- `uv sync` is exact by default. If a package disappears after sync, it was probably not declared in the lockfile or project metadata.
- `uv tool install` is for developer tools like `ruff` or `pytest`, not for project runtime dependencies.
- `uv pip ...` is not the best default for a uv-managed application. It bypasses part of the higher-level project workflow.
- A `uv.toml` file overrides `[tool.uv]` settings in `pyproject.toml`; check both when behavior seems inconsistent.
- `managed = false` disables uv's project environment management for that project. Use it only when another workflow is intentionally responsible for the environment.
- Private package indexes need both index configuration and credentials. One without the other leads to misleading resolution failures.

## Version-Sensitive Notes For 0.10.9

- `uv` follows a release policy that is not strict Semantic Versioning. Minor releases may still include breaking changes, so read the changelog and migration notes before assuming any `0.x` upgrade is trivial.
- Preview functionality is opt-in. If a workflow depends on features such as `native-auth`, make the preview requirement explicit in automation and onboarding docs.
- As of March 12, 2026, PyPI and the maintainer docs agree on `uv 0.10.9`.

## Official Sources

- Docs root: https://docs.astral.sh/uv/
- Installation: https://docs.astral.sh/uv/getting-started/installation/
- Projects guide: https://docs.astral.sh/uv/guides/projects/
- Scripts guide: https://docs.astral.sh/uv/guides/scripts/
- Tools guide: https://docs.astral.sh/uv/guides/tools/
- Alternative indexes: https://docs.astral.sh/uv/guides/integration/alternative-indexes/
- Authentication: https://docs.astral.sh/uv/concepts/authentication/
- Versioning policy: https://docs.astral.sh/uv/policies/versioning/
- PyPI: https://pypi.org/project/uv/
