Best Cursor Settings for Python Developers in 2026

By AICoderScope Team · 12 min read
cursorpythonsetup-guideconfigurationruffpyrightworkflow

Most guides for Cursor talk about the AI features — models, chat, agent mode. They skip the boring part: the settings that determine whether Cursor’s Python suggestions are useful or frustrating. The default configuration for a Python project is worse than what you’d get from a tuned VS Code setup. That’s fixable in about 20 minutes, and the improvement on suggestion quality is immediate.

The settings that actually move the needle for daily Python work: interpreter selection, the cursorpyright vs Pylance situation (which matters more than it sounds), Ruff for formatting and linting, Project Rules for consistent AI output, and pytest integration. Pricing claims here verified against Cursor’s pricing page on May 9, 2026.

If you’re evaluating whether Cursor is worth $20/month before configuring it, read the Cursor IDE Review 2026 first. This guide assumes you’ve already decided to use it.

The one thing every Python developer gets wrong first

Cursor ships with no default Python interpreter selected. Open a new project, ask the AI to write a function that imports your project’s dependencies, and it will either hallucinate module names or tell you the modules “don’t exist” — because it’s looking at the wrong Python environment, or none at all.

Fix this before anything else.

Open the Command Palette (Ctrl+Shift+P on Windows/Linux, Cmd+Shift+P on Mac) and run Python: Select Interpreter. Pick the interpreter inside your .venv/ directory. If you’re using uv — the fast Python package manager that’s rapidly replacing pip + virtualenv in 2026 — run uv sync first so the .venv/ directory exists, then select that interpreter.

After selecting, if Cursor still shows import errors for packages you know are installed: Ctrl+Shift+P → Developer: Reload Window. The language server restarts and re-indexes. This clears most phantom import errors.

Understanding Cursor’s Python language server (don’t skip this)

Cursor does not use Microsoft’s Pylance. It ships its own language server called anysphere.cursorpyright — a customized fork of BasedPyright, which itself is a fork of Microsoft’s Pyright type checker. This is invisible unless you know to look for it, and it causes confusion when you follow standard VS Code Python configuration guides.

What this means practically:

  • If you install Pylance from the extension marketplace, you’ll have two language servers running simultaneously. This causes duplicate errors, conflicting type information, and slow editing. Disable Pylance if it’s installed.
  • Settings prefixed with python.analysis.* may not work. The Cursor language server uses cursorpyright.analysis.* as the settings prefix for project-level overrides.
  • Pyright’s pyrightconfig.json and pyproject.toml [tool.pyright] sections work correctly — the Cursor language server respects them because it’s Pyright-based.

The practical upshot: use pyrightconfig.json (or [tool.pyright] in pyproject.toml) for type checking configuration, not settings.json python.analysis.* entries. That approach is portable across editors and unambiguous about which tool is reading it.

A minimal pyrightconfig.json for a FastAPI project using a local venv:

{
  "venvPath": ".",
  "venv": ".venv",
  "pythonVersion": "3.12",
  "typeCheckingMode": "standard"
}

For projects where you want Cursor’s language server to stay out of the way entirely (you’re using Ruff for diagnostics instead):

{
  "cursorpyright.analysis.typeCheckingMode": "off"
}

Add that to .vscode/settings.json. It turns off type-checking diagnostics from the built-in server without breaking autocomplete or go-to-definition.

Extensions: the three you actually need

Cursor’s extension marketplace runs on Open VSX, not the Microsoft Marketplace. Most Python extensions are available but search names differ slightly from VS Code.

1. Python (ms-python.python) — required. Provides interpreter management, test discovery, the Test sidebar, and the Python debugger. Without it, Python: Select Interpreter doesn’t exist.

2. Ruff (charliermarsh.ruff) — strongly recommended. Ruff is a Rust-based Python linter and formatter that handles everything Black, Flake8, isort, and pyupgrade used to do — but 10–100× faster. In 2026, Ruff has become the default formatting choice for new Python projects. Using Black + Flake8 + isort as separate tools is now unnecessary.

3. Python Debugger (ms-python.debugpy) — needed if you debug via the sidebar. Handles breakpoints, variable inspection, and launch configurations.

Do not install Pylance (ms-python.vscode-pylance). It conflicts with cursorpyright and adds nothing over what’s already built in.

Workspace settings: the complete .vscode/settings.json

Create or update .vscode/settings.json at your project root with this template:

{
  "python.testing.pytestEnabled": true,
  "python.testing.unittestEnabled": false,
  "python.testing.pytestArgs": ["tests"],
  "[python]": {
    "editor.defaultFormatter": "charliermarsh.ruff",
    "editor.formatOnSave": true,
    "editor.codeActionsOnSave": {
      "source.organizeImports.ruff": "explicit"
    }
  }
}

What each line does:

  • pytestEnabled: true — activates the Test sidebar for pytest. Without this, Cursor’s Testing tab shows nothing.
  • unittestEnabled: false — explicitly off; having both active causes test discovery conflicts.
  • pytestArgs: ["tests"] — tells pytest where to look. Adjust if your tests live elsewhere.
  • defaultFormatter: charliermarsh.ruff — routes Python formatting to Ruff instead of the built-in formatter.
  • formatOnSave: true — auto-formats on every save. This is the setting that eliminates most formatting bikeshedding on teams.
  • source.organizeImports.ruff: "explicit" — Ruff reorganizes imports on save using isort-compatible rules.

Commit this file to version control. Every developer on the project gets the same formatting behavior without a “how to set up Cursor” doc.

Project Rules: the biggest lever for Python AI quality

This is the setting most Python developers miss. Cursor’s Project Rules — stored as .mdc files under .cursor/rules/ — are system-level instructions that get injected into every AI prompt in the project. They’re the single most effective way to stop the AI from writing code that doesn’t match your codebase’s patterns.

According to Cursor’s own data shared by community power users: teams that go from roughly 30% suggestion acceptance to 80%+ almost always get there by writing a focused rules file, not by upgrading models.

Create .cursor/rules/python.mdc:

---
description: Python development rules for this project
alwaysApply: true
globs: ["**/*.py"]
---

You are helping develop a Python codebase. Follow these rules:

**Type hints**: Add type hints on all function signatures and class attributes.
Use `from __future__ import annotations` on Python <3.12 projects.

**Formatting**: Code will be formatted with Ruff. Do not add extra blank lines
to work around formatting — let Ruff handle it.

**Imports**: Use absolute imports. Group: stdlib, then third-party, then local.
Ruff's isort handles this on save, so generate imports in any order.

**Error handling**: Use specific exception types, not bare `except:`. Log
exceptions with context; don't swallow them silently.

**Functions**: Keep functions under 30 lines. Extract helpers when a function
does more than one logical thing.

**Tests**: New functions need pytest tests. Test both the happy path and at
least one failure case. Use `pytest.raises` for exception testing.

**No print statements**: Use `logging` module. Debug output via `logger.debug()`.

**Docstrings**: Google-style for public functions only. Private helpers don't
need them unless the logic is non-obvious.

The alwaysApply: true ensures this rule fires on every Python file interaction. The globs pattern means it only attaches when you’re working in .py files — it doesn’t bloat every prompt.

Framework-specific rules

For FastAPI projects, add .cursor/rules/fastapi.mdc:

---
description: FastAPI project rules
alwaysApply: false
globs: ["app/**/*.py", "api/**/*.py"]
---

Stack: Python 3.12, FastAPI, SQLAlchemy 2.0 (async), Pydantic v2, Alembic.

**Route handlers are thin.** Validate input via Pydantic, delegate to service
functions, return Pydantic response models. No business logic in handlers.

**Services accept and return Pydantic models.** Database session is injected
via `AsyncSession = Depends(get_db)`.

**All database queries go through repository functions** in `app/repositories/`.
Never write raw SQL directly in services.

**HTTPExceptions are raised only in routes.** Services raise custom exceptions
defined in `app/core/exceptions.py`. The global exception handler maps these
to HTTP status codes.

**Dependencies use Annotated types:**
`User = Annotated[UserModel, Depends(get_current_user)]`

For Django projects, add .cursor/rules/django.mdc:

---
description: Django project rules
alwaysApply: false
globs: ["**/views.py", "**/models.py", "**/serializers.py"]
---

Stack: Django 5.x, Django REST Framework.

**Views are thin.** Use ViewSets with routers for CRUD. Delegate business
logic to service modules, not views or serializers.

**Querysets use select_related/prefetch_related.** Add these in get_queryset,
not inside loops. N+1 queries are bugs.

**Permission classes are explicit.** Default to IsAuthenticated. Never rely
on global defaults; set per ViewSet.

**Serializers have a single responsibility.** Use separate serializers for
request and response shapes when they differ.

These scoped rules (via globs) only fire when you’re editing files that match the pattern. A rules file for your FastAPI routes doesn’t pollute prompts when you’re editing a test utility.

Model selection for Python work

Cursor gives you the same frontier model lineup regardless of tier — GPT-5.4, Claude Opus 4.6, Gemini 3 Pro, Grok Code, and Cursor’s own Composer 2. The choice matters for Python in specific ways:

Composer 2 — best for iterative edits and multi-file refactors within a known codebase. Fastest response, lowest token cost, and well-tuned for applying diffs cleanly. Use this as your default for everyday coding.

Claude Opus 4.6 — best for complex reasoning tasks: debugging obscure errors, designing a new architecture, writing non-trivial algorithms. Slower and more expensive (request-wise), but produces better reasoning chains for hard problems. The longer it thinks, the better the Python it generates.

GPT-5.4 — strong all-around, slightly faster than Opus on shorter tasks. Scores highest on Aider’s polyglot benchmark at 88.0% correct across languages. Good for one-shot large functions or when you want a second opinion after Composer 2 produces something questionable.

For Python specifically: use Composer 2 by default, switch to Opus 4.6 when you’re stuck on something and have time to wait for a more thoughtful answer.

Testing integration

Once pytestEnabled: true is in your settings, open the Test sidebar (the flask icon in the left panel). Click Refresh Tests. Cursor will discover your test files.

Two things the default configuration doesn’t handle well:

Tests that need a running database or external service — don’t run these from the Test sidebar. Use the integrated terminal: uv run pytest tests/integration/. The sidebar runner doesn’t support service dependencies.

pytest-xdist for parallel test runs — the Test sidebar doesn’t support it, but the terminal does. For large test suites, uv run pytest -n auto runs tests in parallel. Add this to your Project Rules to stop the AI from suggesting slow serial test runs:

When running the full test suite, use `uv run pytest -n auto`.
Single tests or small groups: `uv run pytest tests/path/to/test.py`.

The uv workflow (if you haven’t switched yet)

uv is worth a short note because it changes how Cursor interacts with your Python environment. If you’re still using pip install and virtualenv manually, the migration is low-effort and the daily-use payoff is significant.

Key integration points with Cursor:

  • The AI doesn’t know about uv by default. Your Project Rules should tell it explicitly: “Add packages with uv add <package>. Run scripts with uv run. Activate the venv with source .venv/bin/activate before any direct python invocations.”
  • Agent mode spawns fresh shells that don’t inherit your activated venv. Using uv run instead of python sidesteps this entirely.
  • After uv add <package>, if Cursor shows import errors: run uv sync in the terminal, then Ctrl+Shift+P → Developer: Reload Window.

The one rough edge: the play button in Cursor’s Python files uses the selected interpreter directly, bypassing uv’s dependency resolution. For scripts with inline script metadata (# /// script), run from the terminal with uv run. For regular project code with dependencies already in .venv, the play button works fine.

The settings that move the needle most

If you’re skimming and want the short version, these three changes have the highest impact:

1. Select the right interpreter. Python: Select Interpreter → pick .venv. Every other setting is diminished if the AI can’t see your actual packages.

2. Add a Project Rules file. Even a minimal 15-line .cursor/rules/python.mdc with type-hint and error-handling guidelines cuts hallucinated suggestions noticeably. The ROI on writing this file is higher than upgrading from Pro to Pro+.

3. Enable Ruff with formatOnSave. Once formatting is automatic and consistent, the AI’s generated code lands cleaner on the first try — it has a clear style target to match. Cursor’s tab completions visibly improve when the surrounding code has consistent formatting.

The cursorpyright vs Pylance situation is worth knowing about (if you have Pylance installed, disable it), but it matters less than the above three. You’ll feel the interpreter and rules improvements immediately; the language server situation only shows up if you’re chasing down phantom diagnostics.

Honest take

Cursor’s default out-of-box Python experience is mediocre. The AI is capable; the plumbing is undersettled. Spending 20 minutes on interpreter selection, Ruff configuration, and a Project Rules file moves you from “the suggestions are often wrong” to “the suggestions are usually right.” That’s not a slight exaggeration — it’s the actual gap between configured and unconfigured.

The rules file specifically deserves more attention than it gets in most Cursor tutorials. It’s not a power-user feature; it’s table stakes for consistent Python output. The 1,000–2,500 word rule of thumb (detailed enough to be useful, short enough to stay focused) applies here. Write it once, commit it, let every project interaction benefit.

For the hardware side — if you’re running local models alongside Cursor to cut API costs, the GPU and RAM requirements are on the runaihome.com side of this network: Local LLM Hardware Guide.

Sources

Last updated May 9, 2026. Cursor changes settings and pricing frequently — verify the current state before building workflows around specific behavior.

Was this article helpful?