Writing

Setting Up a Modern Python Development Environment in VS Code

A well-configured editor eliminates friction: formatting happens automatically on save, virtual environments switch seamlessly, and static type mismatches are highlighted before you run your test suite.

This guide walks through configuring a production-grade Python workflow inside Visual Studio Code using pyenv, Poetry (or uv), Ruff, and mypy / pyright.

[!NOTE] Modern Tooling Note While pyenv and Poetry remain industry staples, tools like Astral's uv have also gained significant adoption for all-in-one Python version and environment management. The VS Code settings and extension configuration described below apply equally well to both workflows.

1. Python Version Management with pyenv

Different projects often require distinct Python minor versions. Rather than relying on your operating system's global Python binary, use pyenv.

Installation

  • macOS (via Homebrew):
    brew update
    brew install pyenv
  • Linux / WSL:
    curl https://pyenv.run | bash

Add pyenv to your shell initialization script (~/.zshrc or ~/.bashrc):

export PYENV_ROOT="$HOME/.pyenv"
command -v pyenv >/dev/null || export PATH="$PYENV_ROOT/bin:$PATH"
eval "$(pyenv init -)"

Basic Commands

# List available versions
pyenv install --list

# Install a specific Python release
pyenv install 3.12.7

# Set local version for current directory
pyenv local 3.12.7

2. Managing Environments with Poetry

Initialize your project and virtual environment:

poetry init
poetry install

Configure Poetry to place the .venv directory directly inside your project root, which makes it immediately discoverable by VS Code:

poetry config virtualenvs.in-project true

3. High-Performance Linting & Formatting with Ruff

Historically, Python setups required coordinating Flake8, Black, and isort. Ruff—written in Rust—replaces all three while running 10-100x faster.

Install Ruff and Mypy into your development dependency group:

poetry add --group dev ruff mypy

Install the official Ruff and Mypy Type Checker (or Pylance) extensions from the VS Code Extensions marketplace.

4. Configuring .vscode/settings.json

Create .vscode/settings.json in your project root to standardize settings across your team:

{
  "editor.formatOnSave": true,
  "[python]": {
    "editor.defaultFormatter": "charliermarsh.ruff",
    "editor.codeActionsOnSave": {
      "source.fixAll": "explicit",
      "source.organizeImports": "explicit"
    }
  },
  "python.analysis.typeCheckingMode": "off",
  "ruff.importStrategy": "fromEnvironment",
  "mypy-type-checker.importStrategy": "fromEnvironment"
}

[!TIP] If you prefer Microsoft's Language Server (Pylance/pyright) over mypy, simply set "python.analysis.typeCheckingMode": "basic" and remove the mypy-type-checker entry.

5. Selecting the Python Interpreter

Press Cmd + Shift + P (or Ctrl + Shift + P on Windows/Linux), run Python: Select Interpreter, and pick the .venv/bin/python corresponding to your local project.

Summary

With this setup:

  • Code is automatically formatted and organized by Ruff on every save.
  • Types are verified continuously in the background.
  • Dependencies and interpreter versions remain fully isolated and reproducible.