Установка пакетов в Python: pip, venv и первые ошибки

К концу этой инструкции у вас будет отдельное виртуальное окружение для проекта, установленный в нём пакет requests и понимание, почему его нельзя ставить в систему напрямую. На всё уйдёт минут пятнадцать, включая исправление первой ошибки, которую вы почти наверняка увидите.

Инструкция написана для Python 3.11 и 3.12, менеджер пакетов — pip, он входит в стандартную поставку Python начиная с версии 3.4. Команды приведены и для Windows, и для macOS/Linux — разница только в способе активации окружения.

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

• Установленный Python 3.8 или новее. Проверьте: в терминале выполните python --version (на macOS/Linux часто python3 --version). Должна появиться строка вида Python 3.12.1.
• Доступ к терминалу: PowerShell или cmd на Windows, любой терминал на macOS/Linux.
• Интернет — pip тянет пакеты из репозитория PyPI.
• Права на запись в папку проекта. Права администратора не нужны — и это главная мысль инструкции.

Если python --version выдаёт ошибку «команда не найдена», Python либо не установлен, либо не добавлен в PATH. На Windows переустановите его с python.org и на первом экране установщика поставьте галочку «Add python.exe to PATH».

Почему нельзя просто написать pip install

Соблазн большой: набрать pip install requests и работать. Проблема в том, что так пакет ставится в глобальный Python — один на всю систему. Через полгода у вас три проекта: одному нужен requests версии 2.28, другому 2.31, третий вообще завязан на пакет, который конфликтует с первыми двумя. Глобальная установка складывает их в одну кучу, и рано или поздно обновление под один проект ломает другой.

Виртуальное окружение — это не «продвинутая практика для больших команд». Это первое, что делают перед установкой любого пакета. Один проект — одно окружение.

Виртуальное окружение (сокращённо venv) — это отдельная папка с копией интерпретатора и собственным набором пакетов. Пакеты одного проекта не видят пакетов другого.

Термин: venv

venv — встроенный в Python модуль для создания изолированных окружений. Не требует установки, работает из коробки с Python 3.3+. Не путайте с virtualenv — это отдельный сторонний пакет с похожим назначением, для старта он не нужен.

Шаг за шагом

1. Создайте папку проекта и перейдите в неё.

   mkdir myproject
   cd myproject

   Все следующие команды выполняются внутри этой папки.

2. Создайте виртуальное окружение.

   python -m venv .venv

   На macOS/Linux, если python указывает на Python 2, используйте python3 -m venv .venv. Проверка: в папке проекта появилась директория .venv с подпапками Scripts (Windows) или bin (macOS/Linux).

3. Активируйте окружение.

   Windows (PowerShell):

   .venv\Scripts\Activate.ps1

   Windows (cmd):

   .venv\Scripts\activate.bat

   macOS/Linux:

   source .venv/bin/activate

   Проверка: в начале строки терминала появится префикс (.venv). Теперь python и pip ссылаются на копии внутри окружения, а не на системные.

4. Обновите pip. В свежесозданном окружении часто лежит устаревшая версия.

   python -m pip install --upgrade pip

   Проверка: pip --version покажет номер версии и путь, ведущий внутрь папки .venv.

5. Установите пакет.

   pip install requests

   Проверка: pip show requests выведет имя, версию и путь установки. Или запустите короткую проверку прямо в интерпретаторе:

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

   Если печатается номер версии без ошибок — пакет установлен и импортируется.

6. Зафиксируйте зависимости. Чтобы коллега (или вы через месяц) собрал то же окружение:

   pip freeze > requirements.txt

   Файл requirements.txt хранит список пакетов с точными версиями. Восстановить окружение из него в другом месте: pip install -r requirements.txt.

Зачем закреплять версию пакета

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

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

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

• pip: command not found или 'pip' is not recognized. Вы вне активированного окружения либо pip не в PATH. Используйте форму python -m pip install requests — она вызывает pip через интерпретатор и работает надёжнее.

• PowerShell ругается: Activate.ps1 cannot be loaded because running scripts is disabled on this system. Windows блокирует выполнение скриптов. Разрешите для текущего пользователя одной командой:

  Set-ExecutionPolicy -Scope CurrentUser -ExecutionPolicy RemoteSigned

  После этого повторите активацию. Как альтернатива — активируйте через cmd, там политика не мешает.

• Defaulting to user installation because normal site-packages is not writeable. Это сигнал, что вы ставите пакет в систему без прав, а не в окружение. Проверьте префикс (.venv) в строке терминала: если его нет, окружение не активировано.

• ModuleNotFoundError: No module named 'requests' при запуске скрипта. Пакет установлен в одно окружение, а скрипт запущен другим интерпретатором. Убедитесь, что запускаете через активированное окружение, и проверьте, откуда берётся python: python -c "import sys; print(sys.executable)" — путь должен вести в .venv.

• SSL: CERTIFICATE_VERIFY_FAILED при скачивании. Чаще на корпоративных сетях с прокси или на старых macOS без свежих сертификатов. На macOS запустите скрипт Install Certificates.command из папки установки Python. В корпоративной сети обратитесь к администратору за настройками прокси — обход проверки сертификатов делать не нужно.

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

Добавьте папку .venv в .gitignore — окружение не коммитят в репозиторий, вместо него хранят requirements.txt. Когда проектов станет несколько, посмотрите в сторону инструментов, которые управляют и окружением, и зависимостями одновременно: poetry или uv. Но для первого проекта связки venv + pip хватает полностью — не усложняйте раньше времени.