# How to configure Claude Code to use uv

[Claude Code](https://claude.com/product/claude-code) defaults to [pip](https://pydevtools.com/handbook/reference/pip.md) when it needs to install packages or run scripts. A [CLAUDE.md](https://code.claude.com/docs/en/memory#set-up-a-project-claude-md) file in your project root overrides that default so every session uses [uv](https://pydevtools.com/handbook/reference/uv.md) instead.

> [!TIP]
> Want a ready-made CLAUDE.md that covers uv and other Python tooling? See [How to Set Up CLAUDE.md for a Python Project](https://pydevtools.com/handbook/how-to/how-to-use-the-pydevtools-claude-md-template.md).

## Prerequisites

* [Claude Code](https://claude.com/product/claude-code) installed
* [uv installed](https://docs.astral.sh/uv/getting-started/installation/) on your system
* A uv-based Python project (e.g. created with `uv init`)

## Create a CLAUDE.md file to configure uv usage

### 1. Create a CLAUDE.md file in your project root

Create a file named `CLAUDE.md` in your project's root directory.

> [!TIP]
> You can use the `/init` command in Claude Code to generate a starter CLAUDE.md, then add the uv instructions below.

### 2. Add uv configuration to CLAUDE.md

Copy the following content into your `CLAUDE.md` file:

```markdown
# Python Package Management with uv

Use uv exclusively for Python package management in this project.

## Package Management Commands

- All Python dependencies **must be installed, synchronized, and locked** using uv
- Never use pip, pip-tools, poetry, or conda directly for dependency management

Use these commands:

- Install dependencies: `uv add <package>`
- Remove dependencies: `uv remove <package>`
- Sync environment: `uv sync`
- Lock dependencies: `uv lock`

## Running Python Code

- Run a Python script with `uv run <script-name>.py`
- Run Python tools with `uv run <tool>` (e.g. `uv run pytest`, `uv run ruff`, `uv run mypy`, `uv run pre-commit`)
- Launch a Python REPL with `uv run python`
```

### 3. Verify Claude Code recognizes the configuration

Open Claude Code in your project directory and try these checks:

- Ask Claude to "add pandas as a dependency". It should use `uv add pandas` instead of `pip install pandas`.
- With a Python file open, ask Claude to "run this script". It should use `uv run <filename>`.

> [!IMPORTANT]
> Remember to commit your project-specific CLAUDE.md file to version control so that team members working with Claude Code will automatically get the same uv configuration.

## Additional rules for uv scripts

If your project uses [self-contained scripts with inline metadata](https://pydevtools.com/handbook/how-to/how-to-write-a-self-contained-script.md), add this section to your CLAUDE.md:

```markdown
## Managing Scripts with PEP 723 Inline Metadata

- Run a script with inline metadata: `uv run script.py`
- Add a dependency to a script: `uv add package-name --script script.py`
- Remove a dependency from a script: `uv remove package-name --script script.py`
```

## Apply uv rules globally

To use uv across all your projects, place the configuration in your user-level CLAUDE.md instead of a project-level file. Claude Code reads this file for every session regardless of the working directory.

```
~/.claude/CLAUDE.md
```
```
%USERPROFILE%\.claude\CLAUDE.md
```
## Learn More

* [How to Set Up CLAUDE.md for a Python Project](https://pydevtools.com/handbook/how-to/how-to-use-the-pydevtools-claude-md-template.md) for a more comprehensive starting point
* [How to write Claude Code hooks for Python projects](https://pydevtools.com/handbook/how-to/how-to-write-claude-code-hooks-for-python-projects.md) to enforce uv usage programmatically
* [Claude Code documentation](https://code.claude.com/docs/en/overview)
* [Claude Code project memory guide](https://code.claude.com/docs/en/memory#set-up-a-project-claude-md)