How to configure Claude Code to use uv
Claude Code defaults to pip when it needs to install packages or run scripts. A CLAUDE.md file in your project root overrides that default so every session uses uv instead.
Tip
Want a ready-made CLAUDE.md that covers uv and other Python tooling? See How to use the pydevtools CLAUDE.md template.
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
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:
# 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 pandasinstead ofpip 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, add this section to your CLAUDE.md:
## 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.mdLearn More
- How to use the pydevtools CLAUDE.md template for a more comprehensive starting point
- Claude Code documentation
- Claude Code project memory guide
Also Mentioned In
- uv: A Complete Guide to Python's Fastest Package Manager
- Getting Started with Python Using Claude Code
- Teaching LLMs Python Best Practices
- Claude Code Hooks for uv Projects
- Use Interceptors to teach Claude Code to use uv
- How to install the Astral plugins for Claude Code
- How to use the pydevtools CLAUDE.md template for Python projects
Get Python tooling updates
Subscribe to the newsletter