Настройка VS Code под Python: живой проект без лишних плагинов

В небольшом Python-проекте VS Code легко превращается в источник мелких сбоев: у одного разработчика форматирование запускается при сохранении, у другого — нет, а тесты редактор ищет не в той папке. На примере проекта с каталогами src/ и tests/ настроим интерпретатор, Ruff и pytest так, чтобы команда могла повторить конфигурацию, а личные предпочтения не попали в репозиторий. Пример рассчитан на VS Code 1.85 и новее и Python 3.11.

Сначала разделите настройки на три слоя

У VS Code есть пользовательские настройки, настройки рабочего пространства и конфигурация самих инструментов. Их легко смешать — и получить проект, который работает только на одном компьютере.

• Пользовательские настройки относятся к вам: тема, размер шрифта, расположение панелей.
• Настройки рабочего пространства хранятся в папке .vscode и задают поведение редактора для конкретного репозитория.
• Конфигурация инструментов описывает общие правила проекта. Для Ruff это, например, pyproject.toml; такие правила сможет использовать и редактор, и командная строка.

Для живого примера возьмём небольшой сервис: исходники лежат в src/, тесты — в tests/, окружение Python создаётся в .venv/. Если у вас другая структура, замените пути в примерах. Для Poetry, uv и других менеджеров окружений шаг выбора интерпретатора тот же, но создавать виртуальное окружение следует средствами выбранного инструмента.

Правило, которое экономит больше времени, чем ещё одно расширение: общие правила проекта храните вместе с проектом, личные предпочтения — в пользовательских настройках.

Термин. Интерпретатор — программа, которая запускает Python-код. Виртуальное окружение содержит отдельный интерпретатор и зависимости проекта, чтобы они не смешивались с пакетами других проектов.

Три способа собрать конфигурацию

Здесь не нужно выбирать один-единственный слой и отказаться от остальных. Вопрос в том, где задавать конкретное правило и кто должен его получить.

Практичный вариант для команды — сочетать второй и третий подходы: VS Code знает, какой formatter и тестовый фреймворк использовать, а правила форматирования и lint-проверок лежат в pyproject.toml. Не копируйте один и тот же список правил в несколько файлов: со временем конфигурации разойдутся.

Настраиваем проект на примере Ruff и pytest

1. Откройте корень репозитория

В VS Code выберите именно папку проекта, где находятся src/, tests/ и pyproject.toml, а не только каталог с исходниками. Иначе переменная ${workspaceFolder} будет указывать не туда, а тестовый поиск может пропустить нужную папку. Проверка: в проводнике редактора видны каталоги проекта верхнего уровня.

2. Выберите Python из окружения проекта

Создайте виртуальное окружение тем способом, который принят в проекте, и установите туда его зависимости. Затем откройте палитру команд VS Code, вызовите Python: Select Interpreter и выберите Python из .venv. Не фиксируйте в общих настройках путь вроде /home/alex/project/.venv/bin/python: у коллеги будет другой каталог, а в Windows отличается и расположение исполняемого файла. Проверка: выбранное окружение отображается в строке состояния, а запуск Python из встроенного терминала использует ожидаемую версию.

3. Добавьте общие правила Ruff

Установите Ruff в окружение проекта и добавьте в корневой pyproject.toml минимальную конфигурацию. Пример рассчитан на актуальную ветку Ruff; синтаксис секций нужно сверять с версией, закреплённой в проекте.

[tool.ruff]
line-length = 88

[tool.ruff.lint]
select = ["E", "F"]

Здесь выбраны базовые проверки Pycodestyle и Pyflakes; список можно расширять после того, как команда согласует правила. Ruff не исправит автоматически все возможные ошибки: сначала он покажет диагностику, а форматирование отвечает за единый вид кода. Проверка: из корня проекта команда ruff check . запускается без сообщения о некорректной конфигурации.

4. Привяжите formatter и тесты к рабочему пространству

Создайте каталог .vscode, а в нём файл settings.json. Для Python-расширения VS Code и расширения Ruff выберите форматирование при сохранении; pytest укажите как тестовый фреймворк и задайте каталог тестов.

{
  "[python]": {
    "editor.defaultFormatter": "charliermarsh.ruff",
    "editor.formatOnSave": true
  },
  "python.testing.pytestEnabled": true,
  "python.testing.unittestEnabled": false,
  "python.testing.pytestArgs": ["tests"]
}

Идентификатор formatter относится к расширению Ruff для VS Code. Установите также официальное расширение Python от Microsoft и само окружение с pytest: настройки редактора не устанавливают пакеты автоматически. Проверка форматирования: сохраните Python-файл и убедитесь, что Ruff применил форматирование. Проверка тестов: откройте панель Testing и запустите обнаруженные тесты. Если команда проекта использует не pytest или тесты лежат в другом месте, поменяйте параметры, а не структуру репозитория ради этого примера.

5. Добавьте рекомендации, а не обязательные установки

Чтобы новый участник увидел подсказку об инструментах, создайте .vscode/extensions.json и внесите туда рекомендации. Это не заменяет документацию проекта: расширения не обязаны устанавливаться автоматически, а имя и издателя расширения перед добавлением стоит проверить в Marketplace.

{
  "recommendations": [
    "ms-python.python",
    "charliermarsh.ruff"
  ]
}

Проверка: при открытии проекта VS Code предлагает рекомендованные расширения, а без их установки файлы и репозиторий остаются доступными.

Когда такая связка подходит, а когда мешает

Ruff удобен, когда проект хочет один быстрый инструмент для форматирования и части статических проверок. Цена простоты — необходимость согласовать набор правил и закрепить версию инструмента так, как принято в проекте. Если в репозитории уже используется Black, не включайте параллельно форматирование Ruff: два formatter могут по-разному переписывать файл, и при каждом сохранении появится спор за итоговый вид кода.

Pytest в панели VS Code полезен для короткого цикла «изменил — запустил тест». Но панель не заменяет команду тестирования в CI: важно, чтобы проверка проходила и вне редактора. Если команда запускает тесты специальным скриптом, использует контейнер или требует переменные окружения, настройка автоматического обнаружения может не воспроизвести этот сценарий. Тогда запускайте тесты тем же способом, что и в проекте, и настройте редактор только как дополнительный интерфейс.

Что ломается чаще всего

• В терминале команда не найдена. Ruff или pytest не установлены в выбранное окружение либо терминал открыт до его выбора. Установите зависимости по инструкции проекта и откройте новый терминал.
• Тесты не отображаются. Проверьте, что выбран правильный интерпретатор, pytest установлен, каталог из python.testing.pytestArgs существует и содержит тесты, которые pytest может обнаружить.
• Форматирование при сохранении не происходит. Убедитесь, что расширение Ruff установлено и включено, а formatter задан именно для Python. Если установлен другой formatter, VS Code может использовать его вместо ожидаемого.
• Файлы постоянно меняются после сохранения. Скорее всего, одновременно работают разные formatter или правила Ruff расходятся с настройками проекта. Оставьте один инструмент форматирования и проверьте конфигурацию в pyproject.toml.
• У коллеги настройки не заработали. Проверьте, что в репозитории нет абсолютного пути к вашему Python, расширения рекомендованы, а зависимости описаны в проекте. Файл настроек VS Code сам по себе не устанавливает Python, pytest или Ruff.

Есть и граница применимости: редактор может показывать диагностику локально, но не гарантирует одинаковый результат в CI, если там установлена другая версия Ruff или выбрана другая конфигурация. Закрепите инструмент в зависимостях проекта и запускайте проверки в автоматическом пайплайне теми же правилами. В этой настройке мы разбираем локальный цикл разработки; контейнеры, удалённая разработка и дебаггер — отдельные задачи.

Что проверить после настройки

Сделайте один пробный коммит: измените Python-файл так, чтобы Ruff мог отформатировать его, запустите проверку и выполните тесты из панели. Затем запустите те же проверки командами проекта из терминала и сравните результат. Если он отличается, сначала ищите расхождение в версиях, выбранном интерпретаторе и конфигурации, а не добавляйте ещё одно расширение. После этого внесите в README короткий раздел: как создать окружение, установить зависимости и запустить проверки. Так настройка VS Code останется удобством команды, а не единственным способом понять, как работает проект.