How to configure Cursor rules to use uv
This guide shows you how to configure Cursor editor rules to automatically use uv for Python package management instead of pip. Cursor rules help ensure consistent tooling across your development workflow by providing context to the AI about your project preferences.
Prerequisites
- Cursor editor installed
- uv installed on your system
- A uv-based Python project (e.g. created with
uv init)
Create Cursor rules to use uv
1. Create a global Cursor rules file
To apply uv rules across all your Python projects, create a global Cursor rules file by opening the Cursor Command Palette (View Menu → Command Palette), search for “New Cursor Rule”, and create a new rule named “uv”.
2. Set the rule type
Within the rule, set the “Rule Type” as “Agent Requested”.
3. Write the rule description
In the “Description” field write
Install Python packages, access Python CLI, and manage Python environments4. Write the rule body
In the body of the rule, copy the following:
# Python Package Management with uv
Use uv exclusively for Python package management in all projects.
## 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`Tip
Remember that you can always override these suggestions if needed for specific use cases.
5. Verify the rule
To verify that Cursor is using your uv rules effectively:
Ask Cursor to “add pandas as a dependency”. Cursor should suggest
uv add pandasinstead ofpip install pandas.With a Python file open, ask Cursor to “run this script” - it should suggest
uv run <filename>.
Important
Remember to commit your uv.mdc file to version control so that team members working with Cursor will automatically get the same uv configuration.
Additional rules for uv scripts
You can also instruct uv how to manage self contained scripts with inline metadata. Open your uv.mdc rules file and add:
## 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:
```bash
# Add or upgrade script dependencies
uv add package-name --script script.py
# Remove script dependencies
uv remove package-name --script script.py