How to configure Claude Code to use uv

Tell Claude Code which uv commands the project uses. Then pre-approve only the checks you want to run unattended. Project instructions guide the model; permission rules control approval.

Prerequisites

• Claude Code and uv installed
• A uv project with pyproject.toml and its check tools installed

Record the uv commands

Create or update CLAUDE.md in the project root:

# Python tooling

Use uv for Python operations in this project.

- Run scripts: `uv run python script.py`
- Run tests: `uv run pytest`
- Lint: `uv run ruff check .`
- Check formatting: `uv run ruff format --check .`
- Add dependencies: `uv add <package>` or `uv add --dev <tool>`
- Remove dependencies: `uv remove <package>`
- Sync the environment: `uv sync`
- Update the lockfile after changing constraints: `uv lock`

Do not install project dependencies with pip or run tools outside the
project environment. Use the versions declared by this project.

uv run executes the command inside the project’s virtual environment, ensuring all dependencies are installed first. Commit the instruction file so teammates share the commands. An existing AGENTS.md can also supply these instructions when Claude Code is configured to load it.

Pre-approve selected checks

Merge these entries into .claude/settings.json, or use .claude/settings.local.json for personal rules:

{
  "permissions": {
    "allow": [
      "Bash(uv run pytest)",
      "Bash(uv run ruff check .)",
      "Bash(uv run ruff format --check .)",
      "PowerShell(uv run pytest)",
      "PowerShell(uv run ruff check .)",
      "PowerShell(uv run ruff format --check .)"
    ]
  }
}

These rules name specific command strings. Add further commands only when you want to approve them in advance. A broad Bash(uv run *) rule includes arbitrary Python execution, and uvx can download and execute other tools. Even a test command executes project code; allow it only for a project you trust.

Claude Code also supports * wildcard patterns; see the permission syntax reference. Denying a few pip spellings does not force every possible shell program to use uv.

Confirm instructions and permissions loaded

Start an interactive session in the project root:

claude

Review and accept the workspace trust dialog for your project. Open /memory to inspect instruction files and /permissions to inspect the active rules. Ask Claude to run the configured checks, then verify that its commands use uv run and that the checks actually pass.

If a command still needs approval, inspect deny and ask rules, managed settings, and the active permission mode. A project allow rule does not override a deny rule. Non-interactive claude -p sessions cannot answer a trust dialog or an approval prompt for you.

Keep personal defaults separate

Use ~/.claude/CLAUDE.md for personal instructions and ~/.claude/settings.json for personal permissions. On Windows, ~ is the user profile directory. Project and organization settings also apply; permission rules merge across sources, so a project file does not erase all user rules.