Skip to main content

Setting Up VS Code for Python Development

Visual Studio Code is the most popular editor among Python developers, and for good reason. It strikes a deliberate balance between a lightweight text editor and a full-featured IDE. When configured with the official Python extension and a small set of complementary tools, VS Code becomes a capable environment for everything from exploratory scripting to building production backend services. This guide walks through the setup that a professional Python engineer should apply before writing any significant code.

Why Choose VS Code?​

Before diving into the configuration, it helps to understand why VS Code has become the default choice for so many Python teams.

  • Cross-platform – VS Code runs identically on Windows, macOS, and Linux. Your environment behaves the same way regardless of the underlying operating system.
  • Lightweight and fast – Startup is near-instant, and the editor stays responsive even with large projects.
  • Excellent Python ecosystem – Microsoft maintains the first-party Python and Pylance extensions, which deliver IntelliSense, static analysis, debugging, and test integration.
  • Integrated debugging – Set breakpoints, inspect variables, and step through code without leaving the editor.
  • Native Git integration – Stage, commit, and review changes from within the editor, reducing context switching.
  • Built-in terminal – Run Python scripts, activate virtual environments, and install packages without opening a separate terminal window.
  • Extensibility – The extension marketplace lets you add support for Docker, Jupyter, databases, cloud providers, and AI-assisted coding, but the base installation remains intentionally minimal.

For backend engineers, AI developers, and anyone building maintainable Python software, VS Code provides exactly the tooling needed without the overhead of a heavyweight IDE.

Install Visual Studio Code​

Download the installer for your operating system from https://code.visualstudio.com. Run the installer and accept the default options. On Windows, enable the options to add “Open with Code” actions to the file explorer context menu and to register VS Code as the default editor for supported file types. On macOS, drag the application to the Applications folder as prompted.

After installation, launch VS Code and verify that it opens without errors. You can close any welcome or get-started pages; we will install the necessary extensions next.

Install the Python Extension​

The official Python extension from Microsoft provides the core language support. To install it:

  1. Open the Extensions view by clicking the Extensions icon in the Activity Bar on the side of the window, or by pressing Ctrl+Shift+X (Cmd+Shift+X on macOS).
  2. Search for “Python”.
  3. Locate the extension published by Microsoft (usually the first result) and click Install.

The Python extension bundles several critical capabilities:

  • IntelliSense – autocompletion, signature help, and quick info based on type inference and static analysis.
  • Debugging – a full graphical debugger that integrates with the Python debugger.
  • Testing – discovery and execution of unit tests using pytest or unittest.
  • Jupyter support – .ipynb file editing and interactive Python windows.
  • Environment detection – automatic detection of virtual environments and system interpreters.

In addition to the main Python extension, install Pylance (also by Microsoft). Pylance is a language server that provides faster, more accurate IntelliSense and type checking. It typically installs automatically as a dependency of the Python extension. If not, search for “Pylance” and install it explicitly.

Select the Python Interpreter​

VS Code needs to know which Python interpreter to use for IntelliSense, debugging, and terminal commands. After installing the extensions, open any Python file (or create a new one with a .py extension). VS Code will prompt you to select an interpreter in the bottom-right corner of the status bar. Click on the interpreter indicator (it might show something like “Select Python Interpreter”) and choose from the list of detected environments.

The list includes:

  • Global installations – your system-wide Python, such as the one from python.org or your Linux package manager.
  • Virtual environments – any .venv or venv directories inside your current workspace.
  • Conda environments – if you use Conda, those environments appear as well.

Always select the interpreter that belongs to the virtual environment you created for the project. If you have not yet created a virtual environment, do so before proceeding.

Create and Use a Virtual Environment​

Virtual environments are the standard way to isolate dependencies in Python. Inside your project folder, create an environment:

python -m venv .venv

Activate it:

  • Windows (Command Prompt): .venv\Scripts\activate
  • Windows (PowerShell): .venv\Scripts\Activate.ps1
  • macOS / Linux: source .venv/bin/activate

VS Code automatically detects the .venv folder as soon as it appears. If it does not, open the Command Palette (Ctrl+Shift+P / Cmd+Shift+P), run “Python: Select Interpreter”, and choose the one that points to .venv/bin/python (or .venv\Scripts\python.exe on Windows). The status bar will update to reflect the selected environment.

For a deeper explanation of virtual environments—why they are necessary, how they work, and how they integrate with modern tooling like uv—refer to the dedicated Understanding Virtual Environments in Python guide.

Running Python Programs​

With the interpreter selected, you can run Python files directly from VS Code.

  • Run button – When a Python file is open, a play button appears in the top-right corner of the editor. Click it to execute the current file in the integrated terminal.
  • Integrated terminal – Open the terminal with Ctrl+`` (backtick) or via **View > Terminal**. Activate your virtual environment if it is not active by default, then run python my_script.py`.
  • Command Palette – Run “Python: Run Python File in Terminal” for the same effect without using the mouse.

Whichever method you choose, output appears in the terminal panel. Any errors include clickable file paths that open the offending line directly.

Debugging Python Applications​

VS Code’s debugger is one of its strongest features. It uses the debugpy library to attach to your Python process and provides a familiar graphical interface.

Setting Up a Debug Configuration​

For most use cases, no manual configuration is needed. Open a Python file, switch to the Run and Debug view (the play icon with a bug in the Activity Bar), and click “Run and Debug”. Select “Python File” from the dropdown. VS Code creates a temporary debug configuration and starts your program with the debugger attached.

If you need more control—environment variables, arguments, or a specific module to run—create a launch.json file by clicking the gear icon in the Run view and choosing “Python”. This file lives in .vscode/launch.json and can be committed to version control for team consistency.

Debugging Workflow​

  • Set a breakpoint by clicking in the gutter to the left of a line number. The debugger will pause execution when it reaches that line.
  • Use the debug toolbar to Continue, Step Over, Step Into, or Step Out of functions.
  • Inspect variables in the Variables pane. Expand nested objects and collections.
  • Use the Watch pane to evaluate arbitrary expressions.
  • The Call Stack shows the sequence of function calls that led to the current location.
  • The Debug Console at the bottom lets you execute Python expressions in the context of the paused program. This is invaluable for checking values or testing fixes interactively.

Get comfortable with this workflow early. A productive debugging setup saves hours compared to scattering print() statements.

Code Formatting​

Consistent formatting is a hallmark of professional code. VS Code can apply a formatter automatically every time you save a file.

  • Black – the opinionated formatter that has become the community standard. It reformats your code to a canonical style, ending discussions about spacing and line breaks.
  • Ruff – a fast Python linter that also includes formatting capabilities. If you already use Ruff for linting, its formatter is a natural choice and runs extremely fast.

Configuration​

Install the formatter you prefer (e.g., pip install black inside your virtual environment). Then, open your VS Code settings (Ctrl+,) and set:

  • "editor.formatOnSave": true
  • "[python]": { "editor.defaultFormatter": "ms-python.black-formatter" } if using Black, or "charliermarsh.ruff" if using Ruff.

After enabling format-on-save, every time you save a file, the formatter cleans up indentation, line lengths, and other style details. This enforces a consistent style across the entire project without manual effort.

Linting and Static Analysis​

Linting catches common errors and style violations before runtime. Static type checking with MyPy or Pylance finds type mismatches that would otherwise surface as bugs later.

Linting with Ruff​

Ruff has become the go-to linter for modern Python projects because it is fast and integrates dozens of rules. Install it with pip install ruff. VS Code’s Ruff extension (separate from the base Ruff tool) provides in-editor diagnostics. Install the extension, and it will detect your project’s ruff configuration. Errors and warnings appear as squiggly underlines in the editor, with details in the Problems panel.

Static Type Checking​

Pylance, if you use it as your language server, performs type checking based on the type hints in your code. You can adjust the strictness in VS Code settings under "python.analysis.typeCheckingMode". For projects using mypy as the ground truth, install the MyPy extension and run mypy on the command line. The extension can also integrate with the Problems panel.

Together, a linter and a type checker catch entire categories of mistakes before they ever reach production.

Testing with VS Code​

VS Code integrates with pytest and unittest to provide a visual test runner. After installing pytest in your virtual environment, open the Testing view (the beaker icon in the Activity Bar) and click “Configure Python Tests”. Choose pytest and point it to your test directory (usually tests/).

The Test Explorer displays all discovered tests. From there, you can:

  • Run all tests with one click.
  • Run individual test functions, classes, or files.
  • Debug a specific test by right-clicking it and selecting “Debug Test”. The debugger launches with the same breakpoints, variables, and call stack support as when debugging application code.

Having tests runnable directly in the editor encourages the practice of testing early and often.

Integrated Terminal​

The integrated terminal keeps everything in one window. Press `Ctrl+`` to toggle it. Within the terminal, you can:

  • Activate and deactivate virtual environments.
  • Install and remove packages with pip.
  • Run arbitrary scripts.
  • Execute Git commands.

Because the terminal opens in the project directory and can be configured to use the project’s selected Python interpreter, it eliminates the common problem of accidentally running code with the wrong environment.

A minimal extension set keeps VS Code fast and maintainable. The table below lists the essentials for professional Python engineering, plus optional tools that add value in specific contexts.

ExtensionPurposeRecommended
Python (Microsoft)Core language support: IntelliSense, debugging, testing, environmentsRequired
Pylance (Microsoft)Fast, type-aware language serverRequired
Jupyter (Microsoft)Notebook support for exploratory data workRecommended
GitHub Copilot (GitHub)AI-assisted code completionsOptional (paid)
GitLens (GitKraken)Enhanced Git history, blame, and comparisonOptional
Docker (Microsoft)Dockerfile and container managementUseful for backend/AI
Markdown All in One (Yu Zhang)Markdown editing shortcuts and previewUseful for documentation
Ruff (Astral)Linter and formatter integrationRecommended

Install only what you need. A lean editor stays responsive and reduces the chance of extension conflicts.

VS Code’s settings can be scoped to a workspace by creating a .vscode/settings.json file in your project. Commit this file to version control so that every contributor works with the same configuration. Common settings for a Python project include:

  • "editor.formatOnSave": true – enable automatic formatting.
  • "[python]": { "editor.defaultFormatter": "ms-python.black-formatter" } – choose the default Python formatter.
  • "python.defaultInterpreterPath": ".venv/bin/python" – set the interpreter path explicitly.
  • "files.exclude": { "**/__pycache__": true, "**/*.pyc": true } – hide compiled cache files from the explorer.
  • "editor.rulers": [88] – display a vertical ruler at the maximum line length used by Black and Ruff.
  • "python.analysis.typeCheckingMode": "basic" – enable Pylance type checking with a moderate strictness.

These settings provide a consistent baseline. Adjust them as your project grows.

Common Problems​

Even with a careful setup, a few issues tend to reappear.

  • Wrong interpreter selected – Check the status bar. If it shows a different Python version than expected, run “Python: Select Interpreter” and pick the correct one.
  • Virtual environment not detected – Ensure the .venv folder is at the root of the workspace. Reload the window (Ctrl+Shift+P → “Developer: Reload Window”) if it was created after VS Code launched.
  • Missing Python extension – If syntax highlighting, IntelliSense, or debugging does not work, verify that the Microsoft Python extension is installed and enabled.
  • Formatter not working – Confirm the formatter is installed in the active virtual environment and that the correct default formatter is selected in settings.
  • Linter not running – For Ruff, install both the ruff package and the Ruff extension. Check the Output panel (select “Ruff” in the dropdown) for diagnostic messages.
  • Debugger fails to attach – Make sure no other debugger is attached to the same process. If using a custom launch.json, verify the program and python paths.

Most problems trace back to an environment mismatch or a missing tool in the active virtual environment. Methodically verify the interpreter and installed packages before changing deeper settings.

Best Practices​

  • Create one virtual environment per project and let VS Code select it automatically.
  • Keep the extension set minimal; add new extensions only when a concrete need arises.
  • Enable format-on-save and linting from the start so style and quality become habits, not afterthoughts.
  • Write tests early and run them from the Testing view to maintain a fast feedback loop.
  • Commit code regularly with Git, using VS Code’s source control integration for staging and commit messages.
  • Store workspace settings in .vscode/settings.json and share them with the team to reduce environment friction.

What’s Next​

A properly configured editor eliminates distractions and lets you focus on writing correct, maintainable Python. With VS Code ready, continue building your development foundation.

Work through these guides in order, and you will have a development environment and a mental model that support Python engineering at any scale.