Как зафиксировать зависимости Python в requirements.txt: полное руководство

Введение

При разработке на Python редко удаётся обойтись только стандартной библиотекой. Сторонние пакеты ускоряют работу, но без должного контроля версий могут привести к несовместимостям и ошибкам. Файл requirements.txt — это стандартный способ зафиксировать точные версии зависимостей, чтобы ваш проект одинаково работал на любой машине. В этом руководстве мы разберём, как создавать, обновлять и эффективно использовать requirements.txt, а также рассмотрим типичные ошибки и ответим на частые вопросы.

Что такое requirements.txt и зачем он нужен

requirements.txt — это текстовый файл, в котором перечислены пакеты Python с указанием версий (или диапазонов версий). Он используется инструментом pip для установки всех необходимых зависимостей одной командой. Основные преимущества:

• Воспроизводимость: любой разработчик или сервер может развернуть точно такое же окружение.

• Управление версиями: вы контролируете, какие версии пакетов используются, избегая неожиданных обновлений.

• Упрощение развёртывания: достаточно выполнить pip install -r requirements.txt, чтобы установить всё необходимое.

Требования

• Установленный Python (версия 3.6+).

• Пакетный менеджер pip (обычно идёт в комплекте).

• Базовые навыки работы с командной строкой.

• Виртуальное окружение (рекомендуется, но не обязательно).

Шаг 1: Создание виртуального окружения

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

python -m venv venv

Активируйте его:

• Windows: venv\Scripts\activate

• macOS/Linux: source venv/bin/activate

После активации в приглашении появится имя окружения.

Шаг 2: Установка необходимых пакетов

Установите пакеты, которые нужны для вашего проекта. Например:

pip install requests flask numpy

Эти пакеты будут установлены в виртуальное окружение.

Шаг 3: Генерация файла requirements.txt

Самый простой способ создать requirements.txt — использовать команду pip freeze:

pip freeze > requirements.txt

Эта команда выведет список всех установленных пакетов с точными версиями в формате package==version. Файл будет создан в текущей директории.

Важно: pip freeze включает все пакеты в окружении, включая транзитивные зависимости. Если вы хотите зафиксировать только прямые зависимости, используйте инструменты вроде pipreqs или pip-tools.

Шаг 4: Ручное редактирование requirements.txt

Иногда нужно указать не точную версию, а диапазон. Например:

requests>=2.25.0,<3.0.0
flask~=2.0.0

• == — точная версия.

• >= — минимальная версия.

• ~= — совместимая версия (например, ~=2.0.0 означает >=2.0.0,<2.1.0).

• Можно комбинировать через запятую.

Также можно указывать URL или локальные пути, но это выходит за рамки базового руководства.

Шаг 5: Установка зависимостей из requirements.txt

Чтобы установить все пакеты из файла, выполните:

pip install -r requirements.txt

Эта команда прочитает файл и установит указанные версии. Если какие-то пакеты уже установлены, pip проверит соответствие версий.

Шаг 6: Обновление requirements.txt

При добавлении новых пакетов или обновлении существующих обновите файл:

1. Установите или обновите пакеты вручную. 2. Снова выполните pip freeze > requirements.txt.

Либо используйте pip install --upgrade package_name и затем обновите файл.

Шаг 7: Использование pip-tools для продвинутого управления

pip-tools позволяет разделить прямые и транзитивные зависимости. Установите его:

pip install pip-tools

Создайте файл requirements.in с прямыми зависимостями (без версий или с диапазонами). Затем скомпилируйте:

pip-compile requirements.in

На выходе получите requirements.txt с зафиксированными версиями всех зависимостей. Для обновления используйте pip-compile --upgrade.

Шаг 8: Фиксация зависимостей для разных окружений

Часто проект требует разных зависимостей для разработки и продакшена. Создайте отдельные файлы:

• requirements/base.txt — общие зависимости.

• requirements/dev.txt — для разработки (включая тестовые фреймворки).

• requirements/prod.txt — для продакшена.

В dev.txt можно указать -r base.txt, чтобы не дублировать.

Шаг 9: Проверка целостности зависимостей

Используйте pip check, чтобы убедиться, что все зависимости совместимы:

pip check

Команда выведет список конфликтов, если они есть.

Шаг 10: Автоматизация с помощью CI/CD

Включите установку зависимостей в ваш CI/CD пайплайн. Например, в GitHub Actions:

- name: Install dependencies
  run: pip install -r requirements.txt

Это гарантирует, что тесты и сборка используют те же версии.

Типичные ошибки

1. Использование глобального окружения: установка пакетов без виртуального окружения приводит к конфликтам. 2. Забыли обновить requirements.txt: после добавления пакета файл не обновляется, что вызывает ошибки у других разработчиков. 3. Слишком строгие версии: указание == для всех пакетов может затруднить обновление и привести к конфликтам. 4. Игнорирование транзитивных зависимостей: pip freeze включает все, но иногда это нежелательно. 5. Отсутствие разделения на dev/prod: смешивание зависимостей увеличивает размер продакшен-сборки.

FAQ

Вопрос: Чем отличается requirements.txt от Pipfile?

Ответ: Pipfile — это альтернативный формат, используемый pipenv. Он более структурирован и разделяет dev-зависимости, но requirements.txt остаётся стандартом де-факто.

Вопрос: Можно ли использовать requirements.txt с Poetry?

Ответ: Poetry использует pyproject.toml, но можно экспортировать зависимости в requirements.txt командой poetry export -f requirements.txt.

Вопрос: Как зафиксировать только прямые зависимости?

Ответ: Используйте pipreqs или pip-tools. pipreqs анализирует импорты в коде и создаёт файл только с прямыми зависимостями.

Вопрос: Что делать, если pip install -r requirements.txt выдаёт ошибку?

Ответ: Проверьте совместимость версий, обновите pip, убедитесь, что виртуальное окружение активировано. Можно попробовать установить пакеты по одному для выявления конфликта.

Итог

Файл requirements.txt — незаменимый инструмент для управления зависимостями Python. Следуя шагам из этого руководства, вы сможете создавать воспроизводимые окружения, избегать конфликтов и упростить развёртывание. Не забывайте про виртуальные окружения, регулярно обновляйте зависимости и используйте современные инструменты вроде pip-tools для более тонкого контроля.