Fix Your Broken Python Setup in VSCode Once and For All

Prerequisites

To follow along, you should have VSCode installed and a basic understanding of the Python language. Familiarity with the terminal or command prompt is necessary for running installation commands and project initialization.

Key Libraries & Tools

• UV: A fast Python package installer and resolver written in Rust, used as a modern alternative to Poetry.
• Ruff: An extremely fast Python linter and code formatter.
• Pylance: The default language server for Python in VSCode, providing IntelliSense and type checking.
• Pytest: A framework that makes it easy to write simple and scalable test suites.
• Even Better TOML: An extension for better syntax highlighting and navigation in configuration files.

Project Structure and Initialization

Instead of installing packages globally, we use UV to create an isolated environment. Start by initializing your project in the terminal:

uv init --no-workspace

A professional structure separates the logic from the metadata. Move your code into a src directory and include a __init__.py file to signal that it is a package. Your directory should look like this:

my_project/
└── src/
    └── my_app/
        └── __init__.py
        └── main.py
└── tests/
    └── test_main.py
└── pyproject.toml

To add Pytest as a development dependency, run:

uv add --dev pytest

Solving the Import and Test Discovery Crisis

The most common headache is Pytest failing to find your modules because it doesn't know about the src folder. You fix this by adding a pythonpath setting to your pyproject.toml file:

[tool.pytest.ini_options]
pythonpath = "src"

However, Pylance might still show "reportMissingImports" in the editor even if tests run. You must align the editor's analysis with your runtime path by creating a .vscode/settings.json file:

{
    "python.analysis.extraPaths": ["./src"],
    "python.testing.pytestArgs": ["tests"],
    "python.testing.unittestEnabled": false,
    "python.testing.pytestEnabled": true
}

Professional VSCode Configuration

Managing settings across a team requires moving beyond global user settings. Use Folder Settings within the .vscode directory to ensure every developer on the project uses the same interpreter and formatter.

Recommended Extensions

Share a consistent toolset by creating .vscode/extensions.json. When a team member opens the project, VSCode will prompt them to install the necessary tools:

{
    "recommendations": [
        "ms-python.python",
        "charliermarsh.ruff",
        "tamasfe.even-better-toml"
    ]
}

Syntax Notes and Conventions

• TOML Folding: Use the Even Better TOML extension to collapse large configuration blocks in your pyproject.toml.
• Bundled Formatters: If you use the Ruff extension, enable the useBundled setting to avoid needing a separate local installation of the binary.
• Analysis Paths: Always use relative paths (like ./src) in extraPaths to ensure settings work across different machines.

Tips & Gotchas

• Priority of Settings: Remember that Folder Settings override Workspace Settings, which in turn override User Settings. If your project isn't behaving, check the local .vscode/settings.json first.
• Syncing: Use VSCode's built-in Settings Sync for personal preferences like themes and fonts, but keep project-specific logic (like the Python path) in the repository.
• Source Folder: Never name your root code folder source or src without an __init__.py if you intend to import it as a package; Pylance needs that marker to recognize the package boundary correctly.