Текст и данные · Инструкция
uv python pin закрепить версию Python
`uv python pin <version>` фиксирует предпочитаемую версию Python для каталога в `.python-version`. Перед pin проверьте, что выбранная версия входит в диапазон `requires-python`; после смены интерпретатора старое виртуальное окружение лучше считать отдельным артефактом и пересоздать, если оно создано другим Python.
Короткий ответ
`uv python pin <version>` записывает выбранную версию в `.python-version`; uv использует этот файл при выборе интерпретатора для последующих команд.
Почему важны uv python и pyproject.toml
`.python-version` отвечает на вопрос, какой Python использовать в этом каталоге, а `requires-python` в `pyproject.toml` описывает диапазон совместимости проекта. Команда без аргумента показывает существующий pin, а при отсутствии файла завершится ошибкой. После существенной смены версии Python существующее виртуальное окружение разумно пересоздать и синхронизировать заново.
Совет: Сначала сверяйте `requires-python`: pin не отменяет заявленную совместимость проекта.
Как проверить изменение через Python version
- Шаг 1: Проверьте `requires-python` и выберите pin, входящий в поддерживаемый проектом диапазон.
- Шаг 2: В корне проекта выполните `uv python pin <version>` и проверьте созданный `.python-version`.
- Шаг 3: Решите, должен ли файл быть общим для команды; если да, добавьте его в Git.
- Шаг 4: Проверьте найденный интерпретатор через команды uv и пересоздайте `.venv`, если она была сделана другой версией Python.
Как проверить, что pin действительно применяется
- Выбранная версия входит в `requires-python` проекта.
- `uv python pin` создал или изменил ожидаемый `.python-version` в нужном каталоге.
- Команда uv после pin выбирает именно этот интерпретатор.
- Старое `.venv` не используется вслепую после смены major/minor Python.
- Решено осознанно, должен ли `.python-version` храниться в Git для всей команды.
Чем `.python-version` отличается от `requires-python`
Эти два файла отвечают на разные вопросы. `.python-version` помогает uv выбрать конкретный интерпретатор в рабочем каталоге, а `requires-python` описывает, какие версии Python вообще поддерживает проект. Поэтому pin, который выходит за заявленный диапазон проекта, не делает проект совместимым сам по себе. После записи pin проверьте выбранный Python командой uv и затем создайте или пересоздайте `.venv`. Если файл должен задавать общую версию для команды и CI, добавьте его в Git; локальный эксперимент, наоборот, не должен случайно менять общую политику проекта. После изменения pin перезапустите команду uv, которая создаёт или синхронизирует окружение, чтобы убедиться, что выбран именно ожидаемый интерпретатор.
Предупреждение: Не диагностируйте новый Python на старой `.venv` — это смешивает два независимых состояния.
Где pin не заменяет настройку окружения
Не повышайте Python только редактированием `.python-version`: сначала проверьте совместимость библиотек и нативных расширений, затем пересоздайте среду.
Когда версия Python считается закреплённой
Pin готов, когда новый shell и чистое виртуальное окружение выбирают ожидаемый Python без конфликта с `requires-python`. Если версия в `.python-version` правильная, но uv берёт другую, проверьте расположение файла и контекст каталога до изменения зависимостей: проблема выбора интерпретатора и проблема совместимости пакетов — разные задачи.
Важно: Если pin общий для команды, его проверка должна воспроизводиться на чистом checkout.
Что учитывать
`.python-version` отвечает на вопрос, какой Python использовать в этом каталоге, а `requires-python` в `pyproject.toml` описывает диапазон совместимости проекта. Команда без аргумента показывает существующий pin, а при отсутствии файла завершится ошибкой. После существенной смены версии Python существующее виртуальное окружение разумно пересоздать и синхронизировать заново.
Источники и проверка
Фактическая часть сверена по первичным источникам (в т.ч. uv command reference). Пример и формулировки — редакция N1RO на 2026-09-23.