PyO3 в WSL: фиксируем интерпретатор Python для Rust и VS Code

Почему PyO3 в WSL цепляет Python 3.6 и как указать верный интерпретатор для Rust, cargo и rust-analyzer: переменная PYO3_PYTHON и настройка VS Code в WSL.

При интеграции Rust с Python через PyO3 в WSL выбор интерпретатора способен как обеспечить успешную сборку, так и сорвать её. Частая ловушка — сборка цепляет старую версию Python, даже если кажется, что вы её переопределили. В Windows 11 с WSL и окружением Red Hat 8 попытка принудительно задать Python 3.11 через PYTHON_SYS_EXECUTABLE может всё равно привести к использованию Python 3.6 — версии ниже поддерживаемого диапазона PyO3, из‑за чего падают proc‑макросы.

Проблема

Настройка пытается указать PyO3 на более новый интерпретатор через экспорт переменной окружения, но сборка по‑прежнему обнаруживает Python 3.6. Ошибка выглядит так:

error: the configured Python interpreter version (3.6) is lower than PyO3's minimum supported version (3.7)

Пример проблемы

Минимальный пример подхода, который здесь не сработал: PYTHON_SYS_EXECUTABLE указывает на путь к Python 3.11, но сборка всё равно выбирает 3.6.

export PYTHON_SYS_EXECUTABLE=/path/to/python311

Несмотря на это, скрипт сборки pyo3-ffi видит Python 3.6 и прерывается.

Что происходит

В WSL rust-analyzer и cargo могут запускаться в окружении, отличающемся от вашего интерактивного шелла, а PyO3 строго привязывается к выбранному интерпретатору. На практике проблему решает явное указание исполняемого файла Python для всей цепочки инструментов и гарантия, что rust-analyzer унаследует эту настройку. Сообщение об ошибке прямо показывает: обнаружен интерпретатор 3.6, тогда как PyO3 требует минимум 3.7.

Решение

Явно задайте интерпретатор, который должен использовать PyO3, указав целевой исполняемый файл Python — например, из вашего виртуального окружения. При необходимости сохраните настройку в профиле оболочки.

export PYO3_PYTHON=/home/youruser/.venv/bin/python

Убедитесь, что rust-analyzer внутри VS Code получает то же окружение. Добавьте в settings.json следующую секцию, чтобы процесс анализа использовал нужный интерпретатор:

"rust-analyzer.cargo.extraEnv": {
  "PYO3_PYTHON": "/home/youruser/.venv/bin/python"
}

Проверьте, что Python, доступный в вашей сессии WSL, соответствует тому, который должен использовать PyO3:

which python
python --version

Если изменения окружения применяются не сразу, перезапустите VS Code и, при необходимости, сеанс WSL.

Почему это важно

PyO3 связывается с конкретным экземпляром Python и контролирует минимальную версию. Если сборка линкуется со старым интерпретатором — как с 3.6 в данном случае — развёртка proc‑макросов и скрипты сборки завершаются с ошибкой на ранней стадии. Единообразная настройка интерпретатора для шелла, cargo и rust-analyzer устраняет эти трудноуловимые сбои.

Выводы

Зафиксируйте интерпретатор через PYO3_PYTHON и передайте эту настройку rust-analyzer через settings.json. Проверьте активный интерпретатор в WSL с помощью which и python --version и, при необходимости, перезапустите редактор или WSL, если изменения не вступают в силу сразу. После выравнивания окружения PyO3 перестаёт обращаться к Python 3.6, и сборка идёт против поддерживаемой версии.