How to configure Claude Code to use uv

1. Write the uv rules into CLAUDE.md

Create CLAUDE.md in your project root with these rules. Claude Code loads the file at the start of every session, so the rules survive a restart and reach teammates who clone the repo.

# Python tooling

Use uv for every Python command in this project.

- Run scripts and tools with `uv run`, never bare `python` or `python3`.
- Add and remove dependencies with `uv add` and `uv remove`, never `pip install`.
- Sync and lock the environment with `uv sync` and `uv lock`.
- Run a one-off tool without adding it to the project: `uvx ruff check`.
- For a standalone script, use `uv run script.py` and add its dependencies with
  `uv add --script script.py <package>`.

2. Confirm Claude reaches for uv

Drop a throwaway script in the project root and ask Claude Code to run it:

echo 'print("hello")' > hello.py
claude -p "Run hello.py and show me the output."

Claude runs uv run hello.py. In a directory that has neither pyproject.toml nor these rules, the same request gets python3 hello.py, which is the gap the file closes. Delete hello.py once you have seen the difference.

1. Allowlist the uv commands in .claude/settings.json

Create .claude/settings.json to pre-approve the uv commands and deny pip. Commit it so teammates inherit the same prompts, or keep the rules to yourself in .claude/settings.local.json.

{
  "permissions": {
    "allow": [
      "Bash(uv run:*)",
      "Bash(uv add:*)",
      "Bash(uv remove:*)",
      "Bash(uv sync:*)",
      "Bash(uv lock:*)",
      "Bash(uvx:*)"
    ],
    "deny": [
      "Bash(pip install:*)",
      "Bash(pip3 install:*)",
      "Bash(python -m pip install:*)",
      "Bash(python3 -m pip install:*)"
    ]
  }
}

Every rule matches the literal start of a command, so Bash(uv run:*) covers uv run pytest, uv run ruff check, and uv run python. That same literal matching is why pip takes four deny rules: block only pip install and python -m pip install sails through, which is the spelling Claude picks once the short one is refused.

2. Accept the workspace trust dialog

Allow rules from a project you have not trusted are skipped, so the file you just wrote does nothing yet. Start an interactive session in the project root and accept the dialog before going further:

claude

claude -p skips the trust dialog rather than showing it, so print mode alone can never get you past this point.

3. Confirm the allowlist changed what Claude does

Ask Claude Code to add a dependency and watch whether it needs you:

claude -p "Add idna as a dependency to this project."

uv add idna runs unattended and idna appears under dependencies in pyproject.toml. Run uv remove idna to undo it.

If dependencies is unchanged and Claude reports that uv add idna needed approval, the rules did not load. Claude Code says so on startup:

Ignoring 6 permissions.allow entries from .claude/settings.json: this workspace has not been trusted.

Repeat the trust step from the directory the message names. Trust is keyed to the git repository root, or to the directory you started Claude Code in when there is no repository, so accepting the dialog in a subdirectory leaves the root untrusted.