Установка пакета из PyPI: пошаговый гайд для новичка

К концу этой инструкции у вас будет установленный пакет из PyPI внутри виртуального окружения, и вы сможете импортировать его в своём коде. На чистой машине с уже установленным Python это занимает 5–10 минут вместе с проверками. Разбираем на примере пакета requests — популярной библиотеки для HTTP-запросов, но всё то же работает для любого другого пакета.

Что нужно иметь до начала

Проверьте это до первой команды, иначе споткнётесь на середине.

• Python 3.8 или новее. Проверка: в терминале выполните python --version (в Windows иногда py --version). Должна вывестись строка вида Python 3.12.1. Если версия ниже 3.8 — обновите Python с python.org.
• pip. Это установщик пакетов, он идёт в комплекте с Python начиная с версии 3.4. Проверка: python -m pip --version. Должна вывестись строка вроде pip 24.0 from ....
• Доступ в интернет. pip качает пакеты с серверов PyPI (pypi.org). За корпоративным прокси установка может не пройти без дополнительной настройки — об этом в конце.

PyPI (Python Package Index) — официальный репозиторий пакетов Python. Когда вы пишете pip install requests, pip идёт именно туда, скачивает пакет и его зависимости.

Шаги установки

1. Создайте виртуальное окружение в папке проекта. Это изолированная песочница: пакеты ставятся сюда, а не в системный Python, и проекты не мешают друг другу.

   # перейдите в папку проекта, затем:
   python -m venv venv

   Проверка: рядом появится папка venv с подпапками bin (Linux/macOS) или Scripts (Windows).

2. Активируйте окружение. Команда зависит от системы.

   # Linux / macOS
   source venv/bin/activate
   
   # Windows (PowerShell)
   venv\Scripts\Activate.ps1
   
   # Windows (cmd)
   venv\Scripts\activate.bat

   Проверка: в начале строки терминала появится (venv). Это значит, что окружение активно.

3. Обновите pip внутри окружения. Свежий pip реже спотыкается на новых пакетах.

   python -m pip install --upgrade pip

   Проверка: в выводе будет строка Successfully installed pip-... либо Requirement already satisfied, если он уже свежий.

4. Установите нужный пакет.

   python -m pip install requests

   Проверка: в конце вывода строка Successfully installed requests-2.x.x (номер версии будет актуальный на момент установки).

5. Убедитесь, что пакет импортируется.

   python -c "import requests; print(requests.__version__)"

   Проверка: в терминал выведется номер версии, например 2.32.3. Если версия напечаталась — пакет установлен и готов к работе.

Совет: почему python -m pip, а не просто pip. Форма python -m pip помогает поставить пакет именно в тот Python, который сейчас активен, а не в какой-то другой, случайно попавший в PATH. Это снимает половину проблем «поставил, а импорт не находит».

Половина ошибок установки — это не ошибки установки, а установка не туда: пакет встал в системный Python, а запускаете вы код в другом окружении. Виртуальное окружение и python -m pip закрывают эту проблему разом.

Установка конкретной версии и списка пакетов

Если нужна не последняя, а определённая версия — укажите её через двойное равно:

# ровно эта версия
python -m pip install requests==2.31.0

# не ниже указанной
python -m pip install "requests>=2.28"

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

requests==2.32.3
httpx>=0.27
pydantic

Установить всё разом:

python -m pip install -r requirements.txt

Посмотреть, что уже установлено в окружении: python -m pip list.

Если не получилось

Пять ошибок, которые встречаются чаще всего. Приведён текст, который вы реально увидите, и что делать.

«pip: command not found» или «'pip' is not recognized»

Терминал не находит команду pip. Решение: используйте python -m pip вместо голого pip. Если и это выдаёт ошибку — сам Python не в PATH, проверьте python --version. В Windows попробуйте py -m pip.

«Could not find a version that satisfies the requirement»

pip не нашёл подходящую версию пакета. Частые причины: опечатка в имени (проверьте название на pypi.org), пакет требует более новый Python, чем у вас, или нет сети. Проверьте написание и версию Python. Иногда пакет просто не публикуется под вашу платформу.

«ModuleNotFoundError: No module named 'requests'» после успешной установки

Установка прошла, а импорт не находит пакет. Почти всегда это установка не в то окружение. Убедитесь, что окружение активно (в строке терминала есть (venv)), и ставьте через python -m pip install. Проверьте, каким интерпретатором запускается код: python -c "import sys; print(sys.executable)" — путь должен вести в вашу папку venv.

«error: externally-managed-environment»

Это защита в свежих системных Python (например, в некоторых дистрибутивах Linux и macOS): она не даёт ставить пакеты в системный Python напрямую. Правильное решение — не ломать защиту флагами, а работать в виртуальном окружении (шаги 1–2 выше). Внутри активного venv эта ошибка не появляется.

«Failed building wheel» / долгая компиляция и ошибки компилятора

Возникает у пакетов с частями на C, когда pip не нашёл готовую сборку под вашу систему и пытается собрать из исходников, а компилятора или заголовков нет. Сначала обновите pip (python -m pip install --upgrade pip) — свежий pip чаще находит готовый wheel. Если не помогло — смотрите в документации пакета, какие системные библиотеки нужны для сборки под вашу ОС.

Особый случай: корпоративный прокси или нет доступа к PyPI

Если установка висит и падает с таймаутом, а сеть за прокси — pip умеет ходить через прокси. Точный синтаксис флага и переменные окружения сверьте в актуальной документации pip (раздел про network/proxy), потому что детали зависят от версии и вашей сетевой конфигурации. Не подставляйте наугад чужие настройки прокси.

Что делать дальше

После первой удачной установки закрепите привычки, которые избавят от проблем в будущем:

• Заведите отдельное виртуальное окружение под каждый проект и не ставьте пакеты в системный Python.
• Фиксируйте зависимости в requirements.txt — тогда проект развернётся так же на другой машине.
• Перед установкой незнакомого пакета откройте его страницу на pypi.org: посмотрите дату последнего релиза и число загрузок, чтобы не поставить заброшенный или подозрительный пакет.

Инвалидация и обновление зависимостей, а также инструменты уровня pip-tools или uv — отдельная тема; здесь мы разобрали только базовую установку одного пакета.