Set up Cursor IDE so the "Run Python File" button executes

Source: Notion | Last edited: 2025-08-13 | ID: 24e2d2dc-3ef...

---

GOAL: Set up Cursor IDE so the “Run Python File” button executes uv run python filename.py from any directory level in your workspace.

Quick Setup Checklist

1. Prerequisites Check

# Verify these work:
uv --version
cursor --version  # (or confirm Cursor is installed)

2. Install Required Extensions

In Cursor IDE:

• Install Code Runner (jun-han.code-runner)
• Install Python (ms-python.python)
• Restart Cursor after installation

3. Create Workspace Configuration

Create .vscode/settings.json in workspace root:

{
    "python.defaultInterpreterPath": "${workspaceFolder}/.venv/bin/python",
    "python.terminal.activateEnvironment": false,
    "python.terminal.activateEnvInCurrentTerminal": false,
    "python.terminal.executeInFileDir": false,

    "code-runner.executorMap": {
        "python": "cd \\"$dir\\" && uv run python \\"$fileName\\""
    },
    "code-runner.runInTerminal": true,
    "code-runner.clearPreviousOutput": true,
    "code-runner.saveFileBeforeRun": true,

    "terminal.integrated.env.linux": {
        "UV_PROJECT_ENVIRONMENT": ".venv"
    },
    "terminal.integrated.env.osx": {
        "UV_PROJECT_ENVIRONMENT": ".venv"
    }
}

Create .cursor/settings.json for performance:

{
    "files.watcherExclude": {
        "**/.venv/**": true,
        "**/__pycache__/**": true,
        "**/node_modules/**": true,
        "**/logs/**": true,
        "**/.git/objects/**": true
    }
}

4. Prevent Shell Activation Conflicts (Linux/macOS)

Add to ~/.zshrc (or ~/.bashrc):

# Function to detect and activate Python virtual environment
activate_python_env() {
  # Skip activation in Cursor/VS Code terminals (UV handles execution)
  if [[ "$TERM_PROGRAM" == "cursor" || "$TERM_PROGRAM" == "vscode" ]]; then
    return
  fi

  # ... rest of your existing activation logic ...
}

5. Initialize UV Project

cd /path/to/workspace
uv init
uv add requests  # test dependency

6. Validation Test

Create test_setup.py anywhere in workspace:

import os, sys
print(f"✅ Working dir: {os.getcwd()}")
print(f"✅ Python: {sys.executable}")
print(f"✅ Virtual env: {'YES' if hasattr(sys, 'base_prefix') and sys.base_prefix != sys.prefix else 'NO'}")

import requests
print(f"✅ Requests: {requests.__version__}")
print("🎯 SUCCESS: UV + Cursor integration working!")

7. YOUR TEST:

1. Spawn new Cursor terminal (should show clean prompt without redundant activation)
2. Open test_setup.py in Cursor
3. Click the ▷ “Run Python File” button
4. Verify terminal shows: cd "path" && uv run python "test_setup.py"
5. Verify output shows virtual environment and requests working

8. Multi-Level Test

• Create Python files in subdirectories
• Test “Run Python File” button works from any depth
• All should use same workspace .venv

Success Criteria

✅ “Run Python File” button executes via UV

✅ Works from any directory level

✅ Uses workspace virtual environment

✅ Dependencies available (like requests)

✅ NEW: Clean terminal spawning (no redundant activation messages)

If any step fails, report which step and the error message.

---

Key Changes Made

🎯 High Impact Modifications:

1. Disabled VS Code auto-activation: "python.terminal.activateEnvironment": false
2. Added Linux support: "terminal.integrated.env.linux"
3. Shell conflict prevention: IDE detection in activation function
4. Clean terminal validation: Added to test checklist ⚡ Occam’s Razor Applied:

• Minimal config changes (2 settings flipped, 1 env added)

• Single function modification in shell

• Preserved all existing functionality 🔄 Liskov Substitution Maintained:

• UV execution behavior unchanged

• Code Runner functionality preserved

• Shell activation works identically in non-IDE contexts This replaces redundant activation with clean UV-only execution while maintaining backward compatibility.