How to configure Claude Code to use uv
This guide shows you how to configure Claude Code to automatically use uv for Python package management instead of pip. Claude Code uses CLAUDE.md files to store project memory and context, which helps ensure consistent tooling across your development workflow.
Prerequisites
- Claude Code installed
- uv installed 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
Navigate to your Python project directory and create a file named CLAUDE.md in the root directory. This file will be automatically read by Claude Code when working in this project.
Tip
You can use the /init command in Claude Code to automatically generate a CLAUDE.md file for your project, then customize it with the uv-specific instructions.
2. Add uv configuration to CLAUDE.md
Copy the following content into your CLAUDE.md file:
# 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 dependencies: `uv sync`
## Running Python Code
- Run a Python script with `uv run <script-name>.py`
- Run Python tools like Pytest with `uv run pytest` or `uv run ruff`
- Launch a Python repl with `uv run python`
## Managing Scripts with PEP 723 Inline Metadata
- Run a Python script with inline metadata (dependencies defined at the top of the file) with: `uv run script.py`
- You can add or remove dependencies manually from the `dependencies =` section at the top of the script, or
- Or using uv CLI:
- `uv add package-name --script script.py`
- `uv remove package-name --script script.py`3. Verify Claude Code recognizes the configuration
To verify that Claude Code is using your uv configuration effectively:
Open Claude Code and start a conversation in your project directory.
Ask Claude to “add pandas as a dependency”. Claude should suggest
uv add pandasinstead ofpip install pandas.With a Python file open, ask Claude to “run this script” - it should suggest
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.