Skip to content

How to configure Cursor rules to use uv

by Tim Hopper · Markdown
uv AI Assistants verified with uv 0.13

Use a project rule to tell Cursor’s agent how to manage a uv project. Store it in .cursor/rules/uv.mdc, or add the same instructions to an existing AGENTS.md if the repository shares instructions across agents.

Prerequisites

Create an always-applied project rule

Create .cursor/rules/uv.mdc at the project root with the full contents:

.cursor/rules/uv.mdc
---
description: Use uv for Python dependencies and execution in this repository
alwaysApply: true
---
# Use uv for this Python project

- Run commands from the directory containing pyproject.toml.
- Add runtime dependencies with `uv add <package>` and development
  tools with `uv add --dev <package>`.
- Remove dependencies with `uv remove <package>`.
- Install the project's dependencies with `uv sync`.
- Run Python with `uv run python` or `uv run script.py`; run configured
  project tools with `uv run pytest`, `uv run ruff check .`, and
  `uv run ruff format --check .`.
- Update pyproject.toml and uv.lock together when dependencies change.
- Do not install project dependencies with pip or edit uv.lock by hand.
- Change package managers only when explicitly requested.

alwaysApply: true includes the instructions in every agent chat for this project. An Apply Intelligently rule depends on the agent deciding that its description is relevant; use Always Apply for a project-wide package management convention. Project rules require the .mdc extension.

Commit .cursor/rules/uv.mdc so collaborators receive the same instructions. uv run executes the command inside the project’s virtual environment, ensuring all dependencies are installed first.

Reuse instructions across agents or projects

For a repository that already uses AGENTS.md, add the rule body there instead of maintaining a duplicate .mdc file. Cursor reads AGENTS.md in the project root and subdirectories; no frontmatter is needed.

For personal preferences across repositories, use User Rules in Cursor’s rules settings. Project rules created through the rules settings live in .cursor/rules/. Scope a personal uv preference to uv projects so it does not conflict with repositories that use other tools.

Rules guide agent behavior. They do not configure the editor’s Python interpreter, install uv, or provision a cloud environment. For editor setup, see How to configure Cursor for a uv project.

Add instructions for standalone scripts

For self-contained scripts with inline dependency metadata, append these instructions to the same rule:

## Standalone scripts

- Run a script with inline dependency metadata with `uv run script.py`.
- Add a script dependency with `uv add --script script.py <package>`.
- Remove a script dependency with `uv remove --script script.py <package>`.
- Keep script dependencies in the script's metadata rather than adding
  them to the project's pyproject.toml.

Verify the agent uses the rule

Start a new agent chat in the project and ask it to describe the command it would use to add a development dependency. Expect uv add --dev <package>. Then ask it to run an existing Python script or test suite and inspect the executed command for uv run.

Confirm the command succeeds in the agent’s environment. A correct suggested command does not prove uv is installed or the project dependencies are available. Cloud agents need their own environment setup, including uv and the project’s dependencies.

Last updated on