VS Code para Python: Como Configurar em 2026

Para configurar Python no VS Code, instale o interpretador Python e as extensões Python, Pylance, Python Debugger e Ruff. Abra a pasta do projeto, crie um ambiente .venv e escolha-o em Python: Select Interpreter. Depois use o settings.json abaixo para formatar ao salvar e executar testes. A extensão Python não instala a linguagem: editor, interpretador e bibliotecas são componentes separados.

O Visual Studio Code (VS Code) é um editor gratuito e extensível para Windows, macOS e Linux. Com um ambiente por projeto, você evita instalar dependências no Python errado e mantém terminal, testes e depuração usando o mesmo interpretador.

Neste guia, vamos configurar o VS Code do zero para Python, incluindo extensões essenciais, debugging, linting, formatação automática e atalhos úteis.

Instalando o VS Code

Download

Acesse code.visualstudio.com e baixe a versão para seu sistema operacional. A instalação é simples — siga o assistente padrão.

Comando de terminal

No macOS, abra a paleta com Cmd + Shift + P e execute “Shell Command: Install ‘code’ command in PATH”. No Windows, use a opção de adicionar ao PATH no instalador; no Linux, o pacote normalmente já disponibiliza o comando. Reabra o terminal após a instalação. Isso permite abrir projetos pelo terminal:

code meu-projeto/

Primeiro projeto: Python, ambiente virtual e interpretador

Instale Python antes de continuar: veja os guias para Windows, Linux ou macOS. Abra uma pasta, não apenas um arquivo solto, em File > Open Folder. Abra o terminal integrado pelo menu Terminal > New Terminal.

No Windows, crie o ambiente e instale pytest sem depender da ativação do PowerShell:

py -m venv .venv
.\.venv\Scripts\python.exe -m pip install pytest

No Linux e macOS:

python3 -m venv .venv
./.venv/bin/python -m pip install pytest

Não versione a pasta .venv: adicione-a ao .gitignore. Para entender isolamento e ativação, consulte o guia de ambientes virtuais.

Após instalar as extensões abaixo, execute Python: Select Interpreter na paleta e selecione .venv. No Windows, o executável termina em Scripts/python.exe; no Linux/macOS, em bin/python. Se não aparecer, escolha Enter interpreter path e informe esse caminho. Abra um novo terminal e execute:

python -c "import sys; print(sys.executable)"
python -m pip --version

Os caminhos devem apontar para .venv. Se a ativação automática não ocorrer, use o caminho explícito do executável mostrado acima. Instale bibliotecas com esse interpretador usando -m pip, em vez de confiar em um comando pip que pode pertencer a outro ambiente.

Extensões essenciais

Python (Microsoft)

A extensão oficial integra o VS Code ao interpretador instalado. Pylance e Python Debugger normalmente são instalados junto com ela; confirme no painel de extensões se estão habilitados. Linting e formatação exigem uma ferramenta como Ruff, enquanto notebooks usam a extensão Jupyter.

Instale procurando por “Python” no marketplace de extensões (Ctrl + Shift + X) ou pelo terminal:

code --install-extension ms-python.python

Pylance

O Pylance é o servidor de linguagem da Microsoft para Python. Ele oferece verificação de tipos, autocompletar avançado e análise estática. Geralmente é instalado automaticamente com a extensão Python.

Ruff

O Ruff é um linter e formatador extremamente rápido para Python, escrito em Rust. Ele substitui ferramentas como Flake8, isort e Black:

code --install-extension charliermarsh.ruff

Python Indent

Corrige a indentação automática do Python no VS Code, que nem sempre funciona perfeitamente:

code --install-extension KevinRose.vsc-python-indent

autoDocstring

Gera automaticamente docstrings para funções e classes Python:

code --install-extension njpwerner.autodocstring

Testes sem extensão extra

A extensão Python já integra pytest e unittest ao painel Testing. Não é necessário instalar Python Test Explorer para o fluxo deste guia. O pacote pytest, porém, precisa estar instalado no ambiente selecionado.

Configurações recomendadas

Crie .vscode/settings.json na pasta do projeto. Este exemplo usa configurações do workspace e deixa a formatação restrita aos arquivos Python:

{
    "python.defaultInterpreterPath": "${workspaceFolder}/.venv",
    "python.terminal.activateEnvironment": true,
    "[python]": {
        "editor.formatOnSave": true,
        "editor.defaultFormatter": "charliermarsh.ruff",
        "editor.rulers": [88],
        "editor.tabSize": 4,
        "editor.insertSpaces": true,
        "editor.codeActionsOnSave": {
            "source.fixAll.ruff": "explicit",
            "source.organizeImports.ruff": "explicit"
        }
    },
    "python.testing.pytestEnabled": true,
    "python.testing.unittestEnabled": false,
    "python.testing.pytestArgs": ["tests"],
    "files.trimTrailingWhitespace": true,
    "files.insertFinalNewline": true
}

O caminho para a pasta .venv permite usar o mesmo arquivo no Windows, Linux e macOS. python.defaultInterpreterPath é um padrão inicial: alterá-lo não troca um interpretador já selecionado. Use Python: Select Interpreter para mudar a seleção. Com "explicit", as ações do Ruff acontecem ao salvar explicitamente (Ctrl + S), não no Auto Save.

Configurando o interpretador Python

O VS Code precisa saber qual interpretador Python usar. Isso é especialmente importante quando você tem múltiplas versões ou ambientes virtuais.

1. Pressione Ctrl + Shift + P (ou Cmd + Shift + P no macOS).
2. Digite “Python: Select Interpreter”.
3. Escolha o interpretador desejado da lista.

Confira .venv/Scripts/python.exe no Windows ou .venv/bin/python no Linux/macOS. Em notebooks, escolha também o kernel no canto superior direito: selecionar o interpretador de arquivos .py não garante que um notebook use o mesmo ambiente.

Validando execução e testes

Crie calculadora.py na raiz do projeto:

def somar(a: int, b: int) -> int:
    return a + b


if __name__ == "__main__":
    print(somar(2, 3))

Com .venv ativo no terminal, rode python calculadora.py. O resultado esperado é 5. Crie a pasta tests e o arquivo tests/test_calculadora.py:

from calculadora import somar


def test_somar():
    assert somar(2, 3) == 5

Rode python -m pytest tests: o teste deve passar. Abra o painel Testing e atualize a descoberta de testes. Se ainda não estiver configurado, execute Python: Configure Tests, escolha pytest e a pasta tests. Se funcionar no terminal e falhar no painel, confira o interpretador selecionado e o log em Output > Python.

Para aprofundar o fluxo, veja testes com pytest.

Debugging (depuração)

A extensão Python Debugger fornece a depuração com debugpy. Confira se ela está instalada e habilitada antes de pressionar F5.

Configuração básica

1. Abra um arquivo Python.
2. Clique na margem esquerda ao lado de um número de linha para adicionar um breakpoint (ponto de parada).
3. Pressione F5 ou clique em Run > Start Debugging.
4. Selecione “Python File” na lista que aparece.

Configuração avançada (launch.json)

Para projetos mais complexos, crie um arquivo .vscode/launch.json:

{
    "version": "0.2.0",
    "configurations": [
        {
            "name": "Python: Arquivo Atual",
            "type": "debugpy",
            "request": "launch",
            "program": "${file}",
            "console": "integratedTerminal"
        },
        {
            "name": "Python: Django",
            "type": "debugpy",
            "request": "launch",
            "program": "${workspaceFolder}/manage.py",
            "args": ["runserver"],
            "django": true
        },
        {
            "name": "Python: FastAPI",
            "type": "debugpy",
            "request": "launch",
            "module": "uvicorn",
            "args": ["main:app", "--reload"]
        }
    ]
}

Usando o debugger

Durante a depuração, você tem acesso a:

• Variables: Visualize o valor de todas as variáveis no escopo atual.
• Watch: Adicione expressões para monitorar.
• Call Stack: Veja a pilha de chamadas de funções.
• Debug Console: Execute expressões Python no contexto atual.

Atalhos úteis durante o debugging:

Linting e formatação

Ruff como linter e formatador

Com a extensão Ruff instalada e as configurações acima, seu código será automaticamente:

• Formatado ao salvar: Indentação, espaçamento e quebras de linha são ajustados.
• Verificado em tempo real: Problemas aparecem sublinhados no editor.
• Imports organizados: Os imports são ordenados e agrupados ao salvar.

Configurando o Ruff

Crie um arquivo ruff.toml na raiz do projeto para personalizar as regras:

line-length = 88
target-version = "py312"

[lint]
select = ["E", "F", "I", "N", "W", "UP"]

[format]
quote-style = "double"
indent-style = "space"

Atalhos essenciais para Python

No macOS, substitua Ctrl por Cmd na maioria dos atalhos.

Snippets úteis

O VS Code permite criar snippets personalizados. Vá em File > Preferences > Configure User Snippets > python.json e adicione:

{
    "Main block": {
        "prefix": "main",
        "body": [
            "def main():",
            "    ${1:pass}",
            "",
            "",
            "if __name__ == \"__main__\":",
            "    main()"
        ]
    },
    "Try/Except": {
        "prefix": "tryex",
        "body": [
            "try:",
            "    ${1:pass}",
            "except ${2:Exception} as e:",
            "    ${3:print(f\"Erro: {e}\")}"
        ]
    }
}

Integração com Git

O VS Code tem suporte nativo a Git excelente:

• Source Control (Ctrl + Shift + G): Visualize mudanças, faça commits e gerencie branches.
• GitLens (extensão): Adiciona blame annotations, histórico de arquivos e mais.
• Diff viewer: Compare versões de arquivos lado a lado.

Problemas comuns: o que verificar primeiro

Referências oficiais

• Tutorial Python no VS Code: instalação, ambiente e primeiro programa.
• Configurações da extensão Python: interpretador, terminal e testes.
• Depuração Python: extensão Python Debugger e configurações debugpy.
• Configuração da extensão Ruff: formatter e ações ao salvar.

Próximos passos

Com o VS Code configurado, você está pronto para desenvolver em Python com produtividade. Recomendamos explorar:

• O glossário de termos Python para se familiarizar com conceitos.
• Os tutoriais no blog para aprender na prática.
• As perguntas frequentes para tirar dúvidas comuns.

Antes de decidir o editor, veja também o comparativo completo de VS Code vs PyCharm para Python.

O VS Code também é excelente para outras linguagens. Descubra como configurá-lo para desenvolvimento em Go ou para projetos Kotlin no kotlin.dev.br.