requirements.txt: установка зависимостей через pip

Чтобы установить зависимости Python-проекта из requirements.txt, создайте и активируйте виртуальное окружение в папке проекта и выполните python -m pip install -r requirements.txt. pip прочитает файл построчно, подберёт совместимые версии и установит все пакеты вместе с их зависимостями.

# Windows (cmd или PowerShell)
python -m venv .venv
.venv\Scripts\activate
python -m pip install -r requirements.txt

# macOS и Linux
python3 -m venv .venv
source .venv/bin/activate
python -m pip install -r requirements.txt

Ниже — как создать такой файл (pip freeze, pipreqs, вручную), как в нём указывать версии, подключать другие файлы и хэши, как разделить зависимости для разработки и продакшена, что делать с типичными ошибками установки и когда стоит перейти на pip-tools, uv или Poetry.

Что такое requirements.txt

requirements.txt — текстовый файл со списком пакетов, которые нужны проекту. Каждая строка — одно требование: имя пакета и, при необходимости, ограничение версии:

django>=5.2,<6.1
requests~=2.34
python-dotenv

Файл хранят в корне репозитория рядом с кодом. Другой разработчик, CI-сервер или Docker-образ получает из него то же окружение одной командой. Папку виртуального окружения в git не добавляют: её всегда можно пересоздать из requirements.txt.

Имя requirements.txt принято по договорённости: команда -r принимает файл с любым именем, поэтому в проектах встречаются requirements-dev.txt или папка requirements/. Формат при этом специфичен для pip: другие инструменты (uv, Dependabot, IDE) понимают основную часть синтаксиса, но не обязаны поддерживать все опции.

Как установить зависимости из requirements.txt

Сначала перейдите в папку проекта и активируйте виртуальное окружение — иначе пакеты попадут в системный Python, а в Linux и macOS из Homebrew pip может отказаться ставить их с ошибкой externally-managed-environment. Как создать окружение и активировать его в разных терминалах, подробно описано в статье о виртуальном окружении venv.

Затем запустите установку:

python -m pip install -r requirements.txt

Флаг -r (полная форма — --requirement) говорит pip, что дальше идёт путь к файлу со списком пакетов. Путь указывается относительно текущей папки терминала, поэтому команду запускают из корня проекта или передают полный путь: python -m pip install -r backend/requirements.txt.

Запуск через python -m pip гарантирует, что пакеты установятся именно в тот интерпретатор, который вызывается командой python. Почему это надёжнее, чем просто pip, разобрано в статье о pip и его командах.

В конце успешной установки pip выводит список поставленных пакетов:

Successfully installed certifi-2026.7.22 charset-normalizer-3.5.2 idna-3.20 requests-2.34.2 urllib3-2.8.0

Проверить результат

python -m pip list     # что установлено в окружение
python -m pip check    # нет ли несовместимых версий

No broken requirements found.

Если pip check сообщает о конфликте (X requires Y, which is not installed), установите недостающий пакет или поправьте версии в файле.

Предварительный просмотр без установки

Флаг --dry-run показывает, что pip поставил бы, ничего не меняя в окружении. Удобно перед обновлением рабочего сервера:

python -m pip install --dry-run -r requirements.txt

Would install Django-6.0.9 asgiref-3.12.1 python-dotenv-1.2.4 sqlparse-0.6.0 tzdata-2026.5

Обновить пакеты по файлу

python -m pip install --upgrade -r requirements.txt

pip обновит пакеты до последних версий, которые разрешают ограничения файла. Строки с точной версией (==) не изменятся — чтобы обновить такой пакет, сначала поменяйте версию в файле.

Установка без доступа к интернету

На машине с интернетом скачайте все пакеты вместе с зависимостями в папку, перенесите её и установите без обращения к PyPI:

# на машине с интернетом
python -m pip download -r requirements.txt -d wheels

# на машине без интернета
python -m pip install --no-index --find-links wheels -r requirements.txt

Часть пакетов распространяется в виде колёс под конкретную систему и версию Python (например, charset_normalizer-3.5.2-cp312-cp312-win_amd64.whl). Поэтому скачивайте их на такой же ОС и с той же версией Python, что и на целевой машине.

Как создать requirements.txt

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

Способ	Что попадает в файл	Версии	Когда подходит
pip freeze	Все пакеты окружения, включая зависимости зависимостей	Точные (==)	Зафиксировать рабочее окружение приложения
pip list --not-required	Только пакеты верхнего уровня	Точные (==)	Короткий список того, что ставили сами
pipreqs	Пакеты, которые импортируются в коде	Из окружения или последние с PyPI	Проект без окружения, «грязное» окружение
Вручную	То, что вы перечислили	Любые ограничения	Небольшой проект, библиотека, основа для pip-tools

pip freeze

pip freeze выводит установленные пакеты в формате requirements. Перенаправьте вывод в файл:

python -m pip freeze > requirements.txt

После установки одного requests в чистое окружение получится:

certifi==2026.7.22
charset-normalizer==3.5.2
idna==3.20
requests==2.34.2
urllib3==2.8.0

Плюс pip freeze — точная воспроизводимость: на другой машине встанут те же версии. Минусы проявляются по мере роста проекта:

• Всё вперемешку. Пакеты, которые вы ставили сами, и их зависимости идут одним алфавитным списком. Через полгода трудно понять, нужен ли idna проекту напрямую.
• Остаются «сироты». pip uninstall requests удаляет только сам пакет: certifi, idna, urllib3 и charset-normalizer остаются в окружении и при следующем freeze снова попадают в файл.
• Важно, какое окружение активно. Без активированного venv команда выгрузит все пакеты системного Python — десятки лишних строк.
• Версия Python и платформа не записываются. Пакет, который ставится только в Windows, окажется в файле и сломает установку в Linux, если не добавить к нему маркер окружения.
• Комментарии теряются. Повторный freeze > requirements.txt перезаписывает файл. Сохранить порядок строк и комментарии поможет python -m pip freeze -r requirements.txt > new.txt: пакеты из старого файла останутся на своих местах, а новые pip добавит в конец после строки ## The following requirements were added by pip freeze:.

В Python 3.12 и новее pip freeze не выводит только сам pip; на 3.11 и старше он скрывает также setuptools и wheel. Флаг --all показывает всё, --exclude имя убирает конкретный пакет.

Только пакеты верхнего уровня

Короткий список без зависимостей зависимостей даёт pip list:

python -m pip list --not-required --format=freeze --exclude pip

python-dotenv==1.2.4
requests==2.34.2

--not-required оставляет пакеты, от которых не зависит ни один другой установленный пакет. Обычно это именно то, что вы ставили командой pip install. Такой файл легче читать и обновлять, но он фиксирует только верхний уровень: версии urllib3 или certifi на другой машине могут отличаться.

pipreqs: список по импортам в коде

pipreqs сканирует .py-файлы проекта, находит import и сопоставляет имена модулей с пакетами PyPI. Окружение проекта для этого не нужно.

python -m pip install pipreqs
pipreqs .                    # создать requirements.txt в текущей папке
pipreqs . --print            # только вывести список
pipreqs . --force            # перезаписать существующий файл
pipreqs . --mode compat      # версии через ~= вместо ==

Для файла с импортами os, json, requests, bs4 и yaml результат такой:

beautifulsoup4==4.15.0
PyYAML==6.0.3
Requests==2.34.2

Модули стандартной библиотеки pipreqs пропустил, а bs4 и yaml сопоставил с пакетами beautifulsoup4 и PyYAML. Перед использованием файла проверьте несколько моментов:

• если пакет не установлен локально, pipreqs берёт последнюю версию с PyPI — она может отличаться от той, с которой работает ваш код;
• импорты внутри строк, importlib.import_module() и плагины, которые подключаются по имени, pipreqs не видит;
• не все имена модулей однозначно сопоставляются с пакетами — сам pipreqs предупреждает: Please, verify manually the final list;
• последний релиз pipreqs 0.5.0 (февраль 2024) объявляет поддержку Python только до 3.12. На Python 3.13 и новее pip установит старую версию 0.4.13.

Опции --diff requirements.txt и --clean requirements.txt сравнивают существующий файл с импортами и убирают пакеты, которые в коде не используются.

Вручную

Для небольшого проекта достаточно перечислить пакеты, которые вы импортируете, с разумными ограничениями версий. Такой файл короче и понятнее, чем результат freeze, а точные версии всех зависимостей потом можно зафиксировать через pip-tools или uv — об этом в разделе «Когда requirements.txt недостаточно».

Формат файла и спецификаторы версий

Как указать версию пакета

Запись	Что означает	Пример: какие версии подходят
requests	Любая версия, обычно последняя	все
requests==2.34.2	Ровно эта версия	только 2.34.2
requests>=2.32	Не ниже указанной	2.32.0 и новее
django>=5.2,<6.1	Диапазон: условия через запятую	5.2.x и 6.0.x
requests!=2.32.0	Любая, кроме указанной	все, кроме 2.32.0
requests~=2.34	Совместимый релиз: >=2.34, ==2.*	2.34.0, 2.35.0, но не 3.0
requests~=2.34.0	Совместимый релиз: >=2.34.0, ==2.34.*	2.34.x
requests==2.34.*	Любой патч-релиз ветки	2.34.x

Пробелы вокруг операторов допустимы, регистр в имени пакета не важен, а -, _ и . в именах считаются одинаковыми.

Дополнительные возможности пакета (extras) указывают в квадратных скобках, а условия для разных систем — маркерами окружения после точки с запятой:

uvicorn[standard]>=0.30
colorama; sys_platform == "win32"
uvloop; sys_platform != "win32"
tomli; python_version < "3.11"

Строки, маркер которых не подходит, pip пропускает с сообщением Ignoring uvloop: markers 'sys_platform != "win32"' don't match your environment.

Совет: для приложения (сайта, бота, сервиса) фиксируйте точные версии всех пакетов — так продакшен получит ровно то, что вы проверили. Для библиотеки, которую будут ставить в чужие проекты, используйте диапазоны (>=, ~=), иначе она будет конфликтовать с другими пакетами.

Комментарии, -r и -c

Всё после # (в начале строки или после пробела) pip игнорирует. Длинную строку можно перенести символом \ в конце.

# Веб
django>=5.2,<6.1      # LTS-ветка 5.2 или 6.0
requests~=2.34

# Подключить другой файл требований
-r base.txt

# Ограничить версии, не устанавливая пакеты напрямую
-c constraints.txt

• -r файл подключает другой файл требований целиком: всё из него будет установлено. Путь считается относительно файла, в котором стоит эта строка; текущая папка терминала роли не играет.
• -c файл подключает файл ограничений (constraints). Пакеты из него не устанавливаются сами по себе, но если какой-то пакет понадобится как зависимость, pip возьмёт версию в пределах ограничения.

Пример: в constraints.txt записано urllib3<2.8, а в требованиях есть только requests. pip установит urllib3-2.7.0 вместо 2.8.0, хотя urllib3 в основном списке нет. Файлы ограничений удобны, когда нужно закрепить версию зависимости, не делая её прямой зависимостью проекта, — например, обойти ошибку в свежем релизе. Передать такой файл можно и из командной строки: python -m pip install -r requirements.txt -c constraints.txt.

Другие источники пакетов

Кроме имён с PyPI, файл может содержать:

# пакет из git-репозитория (тег, ветка или коммит после @)
mylib @ git+https://github.com/user/mylib.git@v1.2.0

# локальный wheel-файл или архив
./vendor/somepkg-1.0-py3-none-any.whl

# текущий проект в режиме редактирования
-e .

# другой индекс пакетов; токен берётся из переменной окружения
--index-url https://${PYPI_TOKEN}@pypi.example.com/simple/

Переменные окружения pip подставляет только в форме ${ИМЯ} — так токены и пароли не попадают в репозиторий.

Хэши: защита от подмены пакетов

По умолчанию pip доверяет тому, что отдаёт индекс пакетов. Режим проверки хэшей добавляет к каждой версии контрольную сумму SHA-256: если скачанный файл не совпадёт с ней, установка прервётся.

requests==2.34.2 \
    --hash=sha256:2a0d60c172f83ac6ab31e4554906c0f3b3588d37b5cb939b1c061f4907e278e0

Режим включается автоматически, если хотя бы у одной строки есть --hash, и действует по принципу «всё или ничего»:

• хэши нужны для всех пакетов, включая зависимости зависимостей;
• все версии должны быть закреплены через == (или ссылкой на файл);
• у пакета может быть несколько хэшей — по одному на каждый файл (колёса для разных ОС, архив с исходниками).

Вручную такой файл не пишут. Его генерируют pip-tools или uv из списка прямых зависимостей:

pip-compile --generate-hashes requirements.in -o requirements.txt
# или
uv pip compile --generate-hashes requirements.in -o requirements.txt

При несовпадении хэша pip выводит:

ERROR: THESE PACKAGES DO NOT MATCH THE HASHES FROM THE REQUIREMENTS FILE. If you have updated the package versions, please update the hashes. Otherwise, examine the package contents carefully; someone may have tampered with them.
    requests==2.34.2 from https://files.pythonhosted.org/.../requests-2.34.2-py3-none-any.whl (from -r partial.txt (line 1)):
        Expected sha256 0000000000000000000000000000000000000000000000000000000000000000
             Got        2a0d60c172f83ac6ab31e4554906c0f3b3588d37b5cb939b1c061f4907e278e0

Флаг --require-hashes принудительно включает режим — его ставят в скриптах деплоя, чтобы файл без хэшей не прошёл. Если хэшей нет, pip покажет их для скачанных архивов: Hashes are required in --require-hashes mode, but they are missing from some requirements. Хэш отдельного файла считает команда python -m pip hash путь/к/файлу.whl.

Важно: если в одном файле нужно сочетать пакеты с хэшами и пакеты без них (локальная папка, git-ссылка), в pip 26.2 появился флаг --no-require-hashes: тогда хэши проверяются только там, где они указаны.

Зависимости для разработки и продакшена

Тестам, линтерам и отладчикам на сервере делать нечего: они увеличивают образ и время сборки. Обычно зависимости делят на несколько файлов, где dev-файл подключает основной через -r:

requirements/
├── base.txt     # то, без чего приложение не работает
├── dev.txt      # -r base.txt + pytest, ruff, django-debug-toolbar
└── prod.txt     # -r base.txt + gunicorn, sentry-sdk

# requirements/dev.txt
-r base.txt
pytest>=8
ruff

Разработчик ставит python -m pip install -r requirements/dev.txt, а сервер и Dockerfile — только requirements/prod.txt. В Django-проекте так устанавливают зависимости при сборке Docker-образа и при развёртывании на сервере.

Если в проекте уже есть pyproject.toml, dev-зависимости удобнее описать в группе зависимостей ([dependency-groups]). Современный pip устанавливает группу флагом --group:

[dependency-groups]
dev = ["pytest>=8", "ruff"]

python -m pip install --group dev

Частые ошибки при установке из requirements.txt

Could not open requirements file

ERROR: Could not open requirements file: [Errno 2] No such file or directory: 'requirements.txt'

pip не нашёл файл по указанному пути. Проверьте, что терминал открыт в папке проекта (cd путь/к/проекту), а файл называется именно так — в Windows с выключенным показом расширений легко получить requirements.txt.txt. Если файл лежит в подпапке, укажите путь: -r requirements/dev.txt.

No matching distribution found for requirements.txt

ERROR: Could not find a version that satisfies the requirement requirements.txt (from versions: none)
HINT: You are attempting to install a package literally named "requirements.txt" (which cannot exist). Consider using the '-r' flag to install the packages listed in requirements.txt

Забыт флаг -r: pip ищет на PyPI пакет с именем requirements.txt. Правильно — python -m pip install -r requirements.txt.

Если же в сообщении фигурирует имя реального пакета, либо в нём опечатка, либо нужной версии нет для вашей версии Python. Чаще всего так бывает со старыми закреплёнными версиями на свежем Python: например, файл записан для Python 3.8, а вы ставите на 3.13. Обновите версию пакета в файле или используйте подходящую версию Python.

Конфликт версий: ResolutionImpossible

ERROR: Cannot install requests==2.34.2 and urllib3<1.21 because these package versions have conflicting dependencies.

The conflict is caused by:
    The user requested urllib3<1.21
    requests 2.34.2 depends on urllib3<3 and >=1.26
...
ERROR: ResolutionImpossible: for help visit https://pip.pypa.io/en/latest/topics/dependency-resolution/#dealing-with-dependency-conflicts

Два требования исключают друг друга: здесь requests нужен urllib3 не ниже 1.26, а в файле запрещено всё от 1.21. Блок The conflict is caused by показывает, кто чего требует. Порядок действий:

1. Найдите в файле строки с пакетами из сообщения.
2. Ослабьте ограничение (уберите == или расширьте диапазон) у пакета, который попал в файл как зависимость другого пакета.
3. Если файл получен через pip freeze из другого окружения, пересоберите его: оставьте только прямые зависимости и зафиксируйте версии заново через pip-tools или uv.

Если pip долго перебирает версии с сообщением pip is looking at multiple versions of ... to determine which version is compatible, это тоже признак слишком широких или противоречивых ограничений: сузьте диапазоны у основных пакетов.

Failed building wheel: ошибка сборки пакета

error: metadata-generation-failed
× Encountered error while generating package metadata.
note: This is an issue with the package mentioned above, not pip.

или в других вариантах — Failed building wheel for pycairo, Microsoft Visual C++ 14.0 or greater is required, 'pkg-config' not found.

Колесо (wheel, файл .whl) — готовый к установке пакет. Для популярных библиотек на PyPI лежат колёса под Windows, macOS и Linux. Если колеса для вашей системы или версии Python нет, pip скачивает исходники и пытается собрать пакет сам, а для этого нужны компилятор и системные библиотеки. Что помогает:

• обновите pip (python -m pip install --upgrade pip) — старый pip может не распознать подходящие колёса;
• проверьте, есть ли у закреплённой версии колесо для вашего Python: свежие версии Python часто получают колёса только в новых релизах библиотек, поэтому обновите версию пакета в файле или используйте предыдущую версию Python;
• в Windows установите Microsoft C++ Build Tools, в Debian/Ubuntu — build-essential, python3-dev и dev-пакеты нужной библиотеки (например, pkg-config и libcairo2-dev для pycairo);
• флаг --only-binary :all: запрещает сборку из исходников: pip сразу сообщит, для какого пакета нет готового колеса.

Ошибка длинного пути в Windows (WinError 206)

ERROR: Could not install packages due to an OSError: [WinError 206] The filename or extension is too long
HINT: This error might have occurred since this system does not have Windows Long Path support enabled.

Путь к одному из файлов пакета превысил 260 символов. Так бывает, если проект лежит глубоко в папках, а пакет содержит длинные вложенные пути. Перенесите проект ближе к корню диска (например, C:\projects\site) или включите поддержку длинных путей в Windows — для этого нужны права администратора.

Пакеты установились, но импорт не работает

Если после установки код падает с ModuleNotFoundError, пакеты почти наверняка ушли в другой интерпретатор: окружение не было активировано или редактор запускает другой Python. Проверьте python -m pip --version — в выводе виден путь, куда ставятся пакеты. Подробный разбор — в статье об ошибке ModuleNotFoundError.

Когда requirements.txt недостаточно

Один файл из pip freeze хорошо работает для учебного или небольшого проекта. Когда зависимостей становится много, удобнее разделить два списка: прямые зависимости с понятными ограничениями (что нужно проекту) и lock-файл с точными версиями всего дерева (что установлено на самом деле). Эту задачу решают следующие инструменты.

Инструмент	Где описаны прямые зависимости	Где точные версии	Когда выбрать
pip + requirements.txt	requirements.txt	Тот же файл (pip freeze)	Небольшой проект, скрипты, учебные задачи
pip-tools	requirements.in или pyproject.toml	requirements.txt	Хотите остаться на pip и requirements.txt, но с lock-файлом
uv	pyproject.toml	uv.lock (экспорт в requirements.txt)	Новый проект, важна скорость установки
Poetry	pyproject.toml	poetry.lock	Команда уже работает с Poetry, публикуете пакеты

pip-tools добавляет две команды: pip-compile превращает короткий requirements.in в полный requirements.txt с точными версиями и пометками, откуда взялся каждый пакет, а pip-sync приводит окружение в точное соответствие файлу — лишние пакеты удаляются.

python -m pip install pip-tools
pip-compile requirements.in      # создаёт requirements.txt
pip-sync requirements.txt        # синхронизирует окружение

uv умеет то же самое в режиме совместимости с pip (uv pip compile, uv pip sync, uv pip install -r requirements.txt), а в режиме проекта хранит зависимости в pyproject.toml. Перевести существующий проект можно командой uv add -r requirements.txt, а для старых скриптов деплоя выгрузить файл обратно: uv export --format requirements.txt -o requirements.txt. Результат uv pip compile для requests~=2.34 выглядит так:

# This file was autogenerated by uv via the following command:
#    uv pip compile requirements.in -o requirements.txt
certifi==2026.7.22
    # via requests
charset-normalizer==3.5.2
    # via requests
idna==3.20
    # via requests
requests==2.34.2
    # via -r requirements.in
urllib3==2.8.0
    # via requests

Poetry хранит зависимости в pyproject.toml и poetry.lock. Команда poetry export для получения requirements.txt с Poetry 2.0 не входит в стандартную установку — её добавляет плагин poetry-plugin-export.

В самом pip есть экспериментальная команда pip lock, которая записывает точные версии в стандартный файл pylock.toml; пока она помечена как EXPERIMENTAL. Если вы оформляете код как устанавливаемый пакет, зависимости описывают в pyproject.toml — об этом в статье о том, как создать свою библиотеку Python.

Частые вопросы

Нужно ли добавлять requirements.txt в git?

Да, файл зависимостей — часть исходного кода проекта. В git не добавляют саму папку окружения (.venv, venv): её вносят в .gitignore и пересоздают на каждой машине.

Как добавить новый пакет в requirements.txt?

Установите пакет в активированное окружение и допишите строку в файл вручную, например python-dotenv==1.2.4. Если файл ведётся через pip freeze, просто перезапишите его повторным python -m pip freeze > requirements.txt, а при работе с pip-tools добавьте пакет в requirements.in и снова запустите pip-compile.

Можно ли указать версию Python в requirements.txt?

Нет, файл описывает только пакеты. Требуемую версию Python записывают в README, в requires-python файла pyproject.toml или в .python-version для pyenv и uv. Внутри requirements.txt версия Python учитывается только в маркерах: tomli; python_version < "3.11".

Почему git показывает requirements.txt как бинарный файл?

В Windows PowerShell 5.1 перенаправление > по умолчанию сохраняет файл в кодировке UTF-16. pip и uv такой файл читают, но git считает его бинарным и не показывает изменения. Сохраните файл в UTF-8: python -m pip freeze | Out-File -Encoding utf8 requirements.txt, или работайте в PowerShell 7 и cmd, где этой проблемы нет.

Как удалить все пакеты, перечисленные в requirements.txt?

Команда python -m pip uninstall -r requirements.txt -y удалит пакеты из списка без подтверждений. Проще и надёжнее удалить папку виртуального окружения и создать её заново.

Как установить зависимости в PyCharm или VS Code?

Обе среды выполняют ту же команду pip install -r во встроенном терминале с выбранным интерпретатором проекта. PyCharm при открытии проекта с requirements.txt сам предлагает установить отсутствующие пакеты. Как выбрать интерпретатор venv в редакторе, описано в инструкции по настройке VS Code для Python.

Итог

Устанавливайте зависимости командой python -m pip install -r requirements.txt в активированном виртуальном окружении. Создать файл проще всего через pip freeze, но для читаемого списка подойдут pip list --not-required или ручное описание прямых зависимостей. Для приложения закрепляйте точные версии, для продакшена держите отдельный файл без dev-инструментов, а когда проект вырастет, переходите на lock-файлы pip-tools или uv. Установка самого Python, pip и окружения разобрана в руководстве «Как установить Python» и в разделе «Установка и окружение».