VS Code Setup for Python Development

Introduction

VS Code is the most popular Python editor for good reasons — but out of the box it’s a fancy text editor. The difference between using VS Code and living in it is about fifteen minutes of setup: the right extension, the right interpreter, and a debugger you’ll wonder how you lived without.

This guide walks through that setup once, properly, so every project afterward just works — especially the Streamlit apps you’ll build from this site’s tutorials.

Step 1: The One Essential Extension

Install Python (publisher: Microsoft) from the Extensions panel (Ctrl+Shift+X / Cmd+Shift+X). It brings IntelliSense (autocompletion), linting, debugging, and Jupyter support in one package.

Skip the temptation to install twenty extensions — the Python extension plus VS Code itself covers 95% of what you need. Add Pylance if it isn’t bundled already (it’s the language server that powers autocomplete quality).

Step 2: Select the Right Interpreter

This is the single most important setting. Open a project folder (File → Open Folder), then:

1. Ctrl+Shift+P (Cmd on Mac) → Python: Select Interpreter.
2. Choose your project’s .venv (see the virtual environments guide).

VS Code remembers per-project. Every symptom of “it runs in my terminal but VS Code shows import errors” traces back to this one selection — the editor is using a different Python than your terminal.

Step 3: Settings That Matter

Open Settings (Ctrl+,) or create .vscode/settings.json in your project:

{
  "editor.formatOnSave": true,
  "editor.rulers": [88],
  "python.analysis.typeCheckingMode": "basic",
  "files.exclude": {
    "__pycache__": true,
    ".venv": true
  }
}

formatOnSave is the habit-former: install the Black Formatter extension, and every save produces consistently formatted code — zero mental effort spent on style, ever. The ruler at 88 marks Black’s line length so long lines announce themselves.

Step 4: Debugging — The Superpower

Stop using print() for debugging. Set a red breakpoint by clicking left of a line number, press F5, choose Python File, and:

• Execution pauses at your breakpoint.
• Hover any variable to see its current value.
• The Debug Console lets you run code inside the paused state.
• Step through with F10 (over) and F11 (into).

Watching a loop’s variables change step by step answers questions print never can. This alone is worth the entire setup.

Step 5: The Daily Workflow

• Integrated terminal — Ctrl+` opens a terminal inside your venv context; run scripts and Streamlit without leaving the editor.
• Command palette — Ctrl+Shift+P runs every VS Code command; learn it and menus stop mattering.
• Quick Open — Ctrl+P jumps to any file by typing a fragment.
• Go to Definition — F12 on any function jumps to its source; this is how you read libraries.

Common Issues & Fixes

• Import errors despite installed packages — wrong interpreter selected (Step 2); check the bottom-right status bar shows your .venv.
• Streamlit apps won’t run with F5 — Streamlit needs its own launcher; run streamlit run app.py in the integrated terminal instead of the debugger.
• Slow autocomplete on big projects — let Pylance finish indexing (watch the spinner in the status bar), and exclude .venv from analysis via python.analysis.exclude.
• Format-on-save fights my style — that’s the point; commit to Black and stop thinking about formatting forever.

Key Concepts

• Interpreter selection — per-project Python, the root of half of all setup pain.
• Format on save — delegate style to machines.
• Breakpoints over prints — pause, inspect, step, understand.
• Integrated terminal — editor and shell sharing one context.

What to Try Next

• Debug one of this site’s projects — set a breakpoint inside the quiz app’s answer-checking and watch session state.
• Add pytest test discovery and run tests from the sidebar’s Testing panel.
• Set up Git integration — the source-control sidebar pairs with the Git guide.
• Try Jupyter notebooks in VS Code — # %% cells in a .py file run interactively.

FAQ

VS Code or PyCharm?

VS Code is lighter, faster to start, and general-purpose; PyCharm is heavier with more Python-specific power out of the box. Both are excellent — VS Code’s flexibility wins for most learners who also touch HTML/JS/Markdown.

Do I need the paid extensions?

No — everything in this guide is free. Microsoft’s Python, Pylance, and Black Formatter are all no-cost.

Why does my terminal not activate the venv automatically?

VS Code usually auto-activates the selected interpreter’s venv in new terminals. If it doesn’t, the activation is one command away — and the interpreter selection (Step 2) is what drives it.