ModuleNotFoundError: ставим библиотеки Python и не ломаем окружение

Почему pip install не помогает, чем python отличается от python3, как завести venv и requirements.txt, что делать с externally-managed-environment и Jupyter.

Вы выполнили pip install numpy, pip ответил Successfully installed, а программа всё равно пишет ModuleNotFoundError. Почти всегда это значит, что на компьютере несколько Python: библиотека попала в один, а программу запускает другой. Ниже разберём, как узнать, какой Python работает, какой командой ставить библиотеки, зачем каждой лабораторной своё окружение и что делать с ошибкой externally-managed-environment, с Jupyter и с Windows. Команды проверены на Python 3.14 и pip 26.

Что значит ModuleNotFoundError

Traceback (most recent call last):
  File "/home/student/lab1/lab.py", line 1, in <module>
    import numpy as np
ModuleNotFoundError: No module named 'numpy'

Python искал модуль numpy во всех папках своего списка поиска и не нашёл. Причин четыре:

  • библиотека не установлена;
  • она установлена в другой Python. Их бывает несколько: системный, скачанный с python.org, из Anaconda, отдельное окружение, которое создал PyCharm;
  • имя пакета для pip отличается от имени в import (таблица ниже);
  • опечатка в имени или файл в папке проекта назван так же, как библиотека. Про второе подробно в статье про ошибки Python.

Какой Python запускает программу

Спросите у самого Python, где он лежит. Временно добавьте в начало программы две строки:

import sys
print(sys.executable)

Или выполните в терминале те же команды, которыми запускаете программу:

$ python3 --version
Python 3.14.7
$ python3 -c "import sys; print(sys.executable)"
/home/student/lab1/.venv/bin/python
$ python3 -m pip --version
pip 26.2.1 from /home/student/lab1/.venv/lib/python3.14/site-packages/pip (python 3.14)

В выводе pip видно, в какую папку он ставит пакеты и к какой версии Python относится. Здесь оба пути ведут в .venv, всё сходится. Если sys.executable указывает в одну папку, а pip в другую, библиотеки уходят мимо программы.

python и python3 тоже могут быть разными программами. В macOS и Linux команды python часто нет совсем (zsh: command not found: python), а python3 есть. В Windows обычно пользуются командами python и py, причём python без установленного Python может открыть Microsoft Store.

В редакторе интерпретатор выбирают отдельно от терминала. В VS Code это команда «Python: Select Interpreter», выбранная версия видна в нижней строке окна. В PyCharm: Settings, Project, Python Interpreter.

Почему python -m pip надёжнее, чем pip

Команда pip живёт сама по себе, и заранее неизвестно, к какому Python она привязана. python3 -m pip запускает pip того самого Python, которым вы потом запустите программу.

Два одинаковых войлочных крана над двумя разными чашками, вода льётся мимо одной из них

Отсюда правило:

python3 -m pip install numpy
python3 lab.py

Первое слово в обеих командах одно и то же. В Windows так же с py: py -m pip install numpy, затем py lab.py.

Если pip пишет Requirement already satisfied, а импорт не работает, посмотрите путь в этом сообщении:

Requirement already satisfied: requests in ./.venv/lib/python3.14/site-packages (2.34.2)

Пакет действительно стоит, но в той папке, которую видит другой Python.

Своё окружение для каждой лабораторной

Виртуальное окружение (venv) устроено просто: это отдельная папка со своим Python и своими библиотеками. Что ставите туда, не мешает другим проектам и системе.

cd lab1
python3 -m venv .venv
source .venv/bin/activate          # macOS и Linux
.venv\Scripts\activate.bat         # Windows, cmd
.venv\Scripts\Activate.ps1         # Windows, PowerShell

После активации в начале строки терминала появится (.venv), а python и pip будут указывать внутрь папки:

(.venv) $ which python
/home/student/lab1/.venv/bin/python

Теперь python -m pip install numpy ставит библиотеку только в это окружение. Выйти из него: deactivate.

Если PowerShell не даёт запустить Activate.ps1, в документации Python описано, как разрешить скрипты для своего пользователя. Можно обойтись и без активации: запускайте Python окружения по пути, .venv/bin/python lab.py или .venv\Scripts\python lab.py в Windows.

Папку .venv не отправляют преподавателю и не добавляют в Git. Документация называет окружение одноразовым: его удаляют и создают заново. Чтобы пересоздать его на другом компьютере, нужен список библиотек.

requirements.txt: список библиотек проекта

python -m pip freeze > requirements.txt

После установки одной библиотеки requests файл выглядит так:

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

freeze записывает всё, что стоит в окружении, вместе с зависимостями и точными версиями. Поэтому делайте его из venv. Если запустить его в общем Python, в список попадут библиотеки всех ваших проектов.

На другом компьютере или у проверяющего окружение собирается двумя командами:

python3 -m venv .venv
.venv/bin/python -m pip install -r requirements.txt     # в Windows .venv\Scripts\python

error: externally-managed-environment

В новых версиях Ubuntu и Debian и в Python из Homebrew на macOS установка в системный Python заканчивается так:

$ pip3 install requests
error: externally-managed-environment

× This environment is externally managed
╰─> To install Python packages system-wide, try brew install
    xyz, where xyz is the package you are trying to
    install.
    ...
note: If you believe this is a mistake, please contact your Python installation or OS distribution provider. You can override this, at the risk of breaking your Python installation or OS, by passing --break-system-packages.
hint: See PEP 668 for the detailed specification.

В Ubuntu и Debian вместо brew install в тексте будет apt install python3-xyz. Системным Python пользуются программы самой системы, и её менеджер пакетов управляет им сам. Правило описано в PEP 668: pip отказывается ставить туда пакеты, чтобы не подменить версии, от которых зависит система.

Решение то же, что выше: создайте venv в папке проекта и ставьте библиотеки в него. Флаг --break-system-packages и sudo pip install не используйте. Название флага прямо говорит, чем это может кончиться. Если нужна программа для командной строки, а не библиотека для кода, её ставят через pipx, он сам заводит ей отдельное окружение.

Jupyter: библиотека стоит, а ноутбук её не видит

Ноутбук выполняет код в ядре. Ядро работает отдельным процессом Python, и это не обязательно тот Python, что в терминале. Проверьте в ячейке:

import sys
sys.executable

Ставить библиотеку из ноутбука лучше магической командой %pip:

%pip install numpy

Она запускает pip того Python, на котором работает ядро. После установки появится подсказка Note: you may need to restart the kernel to use updated packages.: перезапустите ядро. Команда !pip install запускает тот pip, который первым найдётся в системном пути PATH, и он может принадлежать другому Python.

Чтобы ноутбук работал в окружении лабораторной, зарегистрируйте его как ядро:

source .venv/bin/activate
python -m pip install ipykernel
python -m ipykernel install --user --name lab1 --display-name "Python (lab1)"

В списке ядер Jupyter или VS Code появится «Python (lab1)». Список зарегистрированных ядер показывает jupyter kernelspec list.

Windows: команда py

В Windows вместе с Python с python.org ставится команда py. Она помогает, когда версий несколько:

py -0                              # какие версии установлены
py -3.12 -m pip install numpy      # поставить в Python 3.12
py -3.12 lab.py                    # запустить им же
py -m venv .venv                   # окружение на версии по умолчанию

С Python 3.14 на смену старому py пришёл менеджер установки Python. В нём список версий выводит py list, а py -0 и py -3.12 оставлены для совместимости (документация).

Имя для pip и имя для import

В коде Команда установки
import cv2 python3 -m pip install opencv-python
from sklearn import ... python3 -m pip install scikit-learn
from bs4 import BeautifulSoup python3 -m pip install beautifulsoup4
from PIL import Image python3 -m pip install Pillow
import docx python3 -m pip install python-docx
import yaml python3 -m pip install PyYAML

pip install sklearn не сработает. Пакет с таким именем намеренно выдаёт ошибку и подсказывает правильное:

The 'sklearn' PyPI package is deprecated, use 'scikit-learn'
rather than 'sklearn' for pip commands.

Короткий порядок действий

  1. Узнайте sys.executable в программе.
  2. Ставьте библиотеки командой <тот же python> -m pip install.
  3. Для каждой лабораторной заведите .venv и requirements.txt.
  4. В Jupyter пользуйтесь %pip и проверьте ядро.

Как с этим помогает Tilpi

Когда неясно, в программе дело или в окружении, проверьте код в исполнителе Tilpi. Он работает в отдельной изолированной машине, где уже стоит Python с numpy, scipy, pandas, matplotlib, sympy и pytest, сам ставит недостающие зависимости и запускает программу. Если код там работает, ищите проблему в своём окружении. Исполнитель запускается из чата задания, а без тарифа работает на уровне «Быстрая» из бесплатных ежемесячных кредитов, общих с чатом.

Запустим ваш код. Даже с телефона.

ИИ-исполнитель соберёт программу в отдельной машине, запустит её и пришлёт вывод и файлы. Ставить компилятор не нужно.

Запустить код в Tilpi