Как импортировать модули и библиотеки в Python

Раздел: Основы Python · Обновлено 31.10.2026

Импорт библиотек в Python выполняется оператором import, который подключает к программе код из стандартной библиотеки, установленных пакетов или ваших собственных файлов. В статье разобраны все формы записи импорта, установка сторонних библиотек, организация своих пакетов, порядок поиска модулей и причины ошибки ModuleNotFoundError.

Содержание статьи

Модуль, пакет и библиотека
Способы записи импорта
Установка сторонних библиотек
Импорт своих модулей и пакетов
1. Относительный импорт внутри пакета
Где Python ищет модули
Порядок импортов в файле
Частые вопросы

Модуль, пакет и библиотека

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

Модуль это один файл .py. Его имя без расширения и есть имя для импорта: файл utils.py подключается как import utils.
Пакет это папка с модулями, которую можно импортировать целиком или по частям через точку. Обычно в ней лежит файл __init__.py.
Библиотека это неформальное название набора пакетов и модулей для одной задачи: стандартная библиотека, requests, pandas.

Стандартная библиотека устанавливается вместе с Python, и ее модули (math, random, datetime, json, os) доступны сразу. Сторонние библиотеки нужно сначала установить. Подробно о том, как устроен модуль и что происходит при его первом импорте, рассказано в статье про модули Python.

Способы записи импорта

Синтаксис импорта один и тот же для встроенных, установленных и собственных модулей. Отличается только то, какие имена появляются в вашем коде.

Модуль целиком через import

Самая надежная форма. Все содержимое доступно через имя модуля и точку, поэтому всегда видно, откуда взялась функция.

import math
import random

print(math.sqrt(16))         # 4.0
print(math.pi)               # 3.141592653589793
print(random.randint(1, 6))  # случайное число от 1 до 6

Отдельные имена через from ... import

Если из модуля нужно две-три функции, их можно импортировать напрямую и вызывать без префикса.

from math import sqrt, floor
from datetime import date

print(sqrt(25))      # 5.0
print(floor(3.7))    # 3
print(date.today())  # текущая дата

Минус в том, что имена могут столкнуться. Если в программе есть своя функция sqrt или две библиотеки экспортируют одинаковое имя, последний импорт молча перезапишет предыдущий.

Псевдонимы через as

Ключевое слово as дает модулю или функции другое имя. Для популярных библиотек сложились общепринятые сокращения, и их стоит соблюдать: так ваш код поймут другие программисты.

import datetime as dt
from collections import Counter as C

print(dt.date(2026, 1, 1).weekday())  # 3
print(C('abracadabra').most_common(1))  # [('a', 5)]

# устоявшиеся сокращения сторонних библиотек
# import numpy as np
# import pandas as pd
# import matplotlib.pyplot as plt

Почему не стоит писать from module import *

Звездочка загружает в программу все публичные имена модуля. Из кода становится непонятно, где определена функция, редактор хуже подсказывает, а случайное совпадение имен приводит к трудноуловимым ошибкам. Такую форму допустимо применять только в интерактивной консоли для быстрых экспериментов.

Установка сторонних библиотек

Сторонние пакеты скачиваются из каталога PyPI менеджером pip. Устанавливать их лучше в виртуальное окружение проекта, чтобы версии не конфликтовали между проектами.

python -m pip install requests
python -m pip install "pandas>=2.2"
python -m pip list

Запуск через python -m pip гарантирует, что пакет попадет именно в тот Python, которым вы будете запускать программу. Это частая причина ошибки, когда библиотека вроде бы установлена, а импорт не работает. Все команды и ключи pip собраны в руководстве по pip.

Имя пакета для установки и имя модуля для импорта не всегда совпадают:

Установка	Импорт
`pip install beautifulsoup4`	`from bs4 import BeautifulSoup`
`pip install pillow`	`from PIL import Image`
`pip install python-docx`	`import docx`
`pip install opencv-python`	`import cv2`
`pip install scikit-learn`	`import sklearn`

Импорт своих модулей и пакетов

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

project/
    main.py
    game/
        __init__.py
        settings.py
        level/
            __init__.py
            start.py
            boss.py

Из main.py к модулям обращаются через точку по пути от корня проекта. Функцию run() из start.py можно подключить тремя способами:

import game.level.start
game.level.start.run()

from game.level import start
start.run()

from game.level.start import run
run()

Импортировать можно только модули и объекты внутри них. Запись вида import game.level.start.run() с вызовом функции синтаксически неверна.

Относительный импорт внутри пакета

Модули одного пакета могут ссылаться друг на друга относительно своего положения. Одна точка означает текущий пакет, две точки родительский.

# файл game/level/boss.py
from .start import run          # соседний модуль в level
from ..settings import DIFFICULTY  # модуль уровнем выше

Относительные импорты работают только внутри пакета. Если запустить python game/level/boss.py напрямую, Python выдаст ImportError: attempted relative import with no known parent package. Запускайте модуль из корня проекта командой python -m game.level.boss.

Файл __init__.py выполняется при первом импорте пакета. Его можно оставить пустым или поднять в нем часто используемые имена, чтобы писать from game import run. Начиная с Python 3.3 папка без этого файла тоже импортируется как пакет пространства имен, но явный __init__.py делает структуру понятнее.

Где Python ищет модули

При импорте интерпретатор перебирает каталоги из списка sys.path и берет первый найденный модуль с подходящим именем. Порядок поиска такой: папка запускаемого скрипта, пути из переменной окружения PYTHONPATH, стандартная библиотека, папка site-packages с установленными пакетами.

import sys
import json

for path in sys.path[:3]:
    print(path)
print(json.__file__)  # откуда загружен модуль

Отсюда самая коварная ошибка новичков: файл, названный как библиотека. Если сохранить свой скрипт как random.py или requests.py, то import random загрузит его, а не настоящий модуль, и программа упадет с AttributeError. Переименуйте файл и удалите рядом папку __pycache__.

Порядок импортов в файле

Импорты пишут в начале файла, после строки документации. Руководство PEP 8 советует делить их на три группы с пустой строкой между ними: стандартная библиотека, сторонние пакеты, модули проекта. Внутри группы имена идут по алфавиту.

import json
import os
from pathlib import Path

import requests

from game.level import start

Модуль импортируется один раз за запуск программы: повторный import берет готовый объект из кеша sys.modules. Расставлять импорты вручную не обязательно, это умеет делать линтер, о котором рассказано в статье про Ruff. Формальное описание механизма импорта есть в справочнике языка.

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

Ответы на вопросы, которые чаще всего возникают при подключении библиотек.

Что делать при ошибке ModuleNotFoundError?

Проверьте три вещи: пакет установлен командой python -m pip install в тот же интерпретатор, что запускает программу; в редакторе выбрано нужное виртуальное окружение; имя модуля для импорта написано правильно, оно может отличаться от имени пакета.

Как перезагрузить модуль без перезапуска программы?

Используйте importlib.reload(module). Это нужно в интерактивной консоли или Jupyter, когда вы меняете код своего модуля и хотите сразу проверить результат.

Можно ли импортировать модуль внутри функции?

Можно, импорт будет выполнен при первом вызове функции. Так делают с тяжелыми библиотеками, которые нужны редко, или чтобы разорвать циклический импорт. В остальных случаях держите импорты вверху файла.

Как посмотреть, что есть в модуле?

Функция dir(module) выводит список имен, а help(module) показывает документацию. В консоли это быстрее, чем искать описание в интернете.