Module und Pakete in Python: import, pip, venv und Bibliotheken einfach erklärt

Ein Modul in Python ist eine gewöhnliche Datei mit Code, und import ist der Weg, Funktionen und Klassen daraus zu verwenden. Aus Modulen entstehen Pakete, aus Paketen Bibliotheken. Damit fremde Bibliotheken verschiedener Projekte sich nicht in die Quere kommen, installiert man sie in eine virtuelle Umgebung (venv). Wir gehen die ganze Kette durch: was beim Import passiert, wie ein Paket aufgebaut ist, wie pip und venv zusammenarbeiten und welche lazy imports in Python 3.15 neu sind.

Modul, Paket, Bibliothek: der Unterschied

Die Begriffe „Bibliothek“, „Paket“ und „Modul“ werden im Gespräch oft vermischt, das ist üblich. Technisch gesehen lädt import immer ein Modul oder ein Paket, und pip installiert eine Distribution von PyPI, in der Pakete enthalten sind.

Wie import in Python funktioniert

Es gibt mehrere Formen des Imports, alle kommen im echten Code vor:

import math                    # ganzes Modul, Zugriff über math.sqrt
from math import sqrt, pi      # einzelne Namen
import datetime as dt          # Alias
from collections import Counter as C

print(math.sqrt(16), sqrt(9), pi)
print(dt.date.today())

Aliase sind bei großen Bibliotheken üblich: import numpy as np, import pandas as pd. Die Konstruktion from module import * sollten Sie vermeiden: Sie verschmutzt den Namensraum und verbirgt, woher ein Name stammt.

Was import tatsächlich tut

1. Sucht das Modul im Cache sys.modules. Ist es schon geladen, gibt er es einfach zurück.
2. Ist es nicht geladen, sucht er die Datei in den Ordnern von sys.path: Ordner des gestarteten Skripts, Standardbibliothek, site-packages der Umgebung.
3. Führt die gefundene Datei vollständig aus, von oben nach unten.
4. Legt das Modulobjekt im Cache ab und bindet es an den Namen.

Daraus ergeben sich zwei praktische Folgerungen. Ein erneuter import desselben Moduls ist nahezu kostenlos, der Code wird kein zweites Mal ausgeführt. Und der gesamte Code auf oberster Ebene eines Moduls, einschließlich print und schwerer Berechnungen, läuft beim Import.

import sys
for p in sys.path:
    print(p)
print("math" in sys.modules)

if __name__ == "__main__"

Da der Import die Datei ausführt, braucht man eine Möglichkeit, zwischen „als Skript gestartet“ und „importiert“ zu unterscheiden. Dafür gibt es die Variable __name__: Beim Start der Datei ist sie "__main__", beim Import der Name des Moduls.

# kategorien.py
def guess(title: str) -> str:
    return "essen" if "cafe" in title.lower() else "sonstiges"

if __name__ == "__main__":
    print(guess("Cafe um die Ecke"))   # wird nur bei python kategorien.py ausgeführt

Für ein Paket gibt es eine Alternative: eine Datei __main__.py im Paket und den Start mit python -m ausgaben.

Standardmodule von Python

Python kommt mit vielen Batterien: Hunderte eingebaute Module stehen sofort zur Verfügung, ohne Installation. Die gebräuchlichsten:

Die vollständige Liste der Module der Standardbibliothek steht in sys.stdlib_module_names (Python 3.10+). Was ein Modul enthält, zeigen dir(math) und help(math).

Ein eigenes Paket: Projektstruktur

Wenn es viele Module gibt, fasst man sie zu einem Paket zusammen. Eine verbreitete Anordnung ist das src-Layout:

expenses-project/
├── pyproject.toml
└── src/
    └── expenses/
        ├── __init__.py
        ├── cli.py
        ├── parsing.py
        ├── categories.py
        └── report.py

Innerhalb des Pakets importieren sich die Module gegenseitig über den Paketnamen (from expenses.categories import guess) oder relativ (from .categories import guess). Der relative Import funktioniert nur innerhalb des Pakets, nicht in einer Datei, die direkt als Skript gestartet wird.

pip in Python: Bibliotheken installieren

Fremde Bibliotheken liegen im Verzeichnis PyPI, installiert werden sie mit dem Programm pip, das mit Python geliefert wird. Am zuverlässigsten rufen Sie pip über den Interpreter auf. So landet die Bibliothek sicher in dem Python, mit dem Sie den Code ausführen.

python -m pip install requests          # installieren
python -m pip install "pandas>=2.3"     # mit Versionsangabe
python -m pip install --upgrade requests
python -m pip uninstall requests        # entfernen
python -m pip list                      # installierte Pakete auflisten
python -m pip show requests             # Version und Abhängigkeiten
python -m pip freeze > requirements.txt
python -m pip install -r requirements.txt

Unter Windows verwendet man oft statt python den Launcher py. Fehlt pip, installiert es das eingebaute Modul: python -m ensurepip --upgrade.

Beliebte Bibliotheken für Python

Auf PyPI gibt es Hunderttausende Pakete, doch in den meisten Projekten taucht immer dieselbe kurze Liste auf. Beginnen Sie damit, statt nach exotischen Lösungen zu suchen.

Beachten Sie: Der Name zum Installieren und der Name zum Importieren stimmen nicht immer überein. Installiert wird pip install pillow, importiert wird from PIL import Image. Installiert wird opencv-python, importiert wird cv2. Wenn import direkt nach der Installation fehlschlägt, prüfen Sie in der Dokumentation des Pakets, unter welchem Namen es importiert wird.

Bibliotheken unter Linux installieren

In aktuellen Versionen von Debian und Ubuntu endet pip install im Systempython mit dem Fehler externally-managed-environment (PEP 668). Das ist ein Schutz: Das Systempython gehört dem Paketmanager des Betriebssystems, und pip soll es nicht beschädigen. Die richtige Lösung ist nicht --break-system-packages, sondern eine virtuelle Umgebung.

venv in Python: die virtuelle Umgebung

Eine virtuelle Umgebung ist ein eigener Ordner mit einer eigenen Kopie (einem Verweis) des Interpreters und einem eigenen Ordner site-packages. Die Bibliotheken, die darin installiert werden, sieht nur dieses Projekt. So kann ein Projekt Django 4 verwenden und ein anderes Django 5, ohne dass es Konflikte gibt.

Das Modul venv ist Bestandteil von Python und muss nicht separat installiert werden (unter Debian und Ubuntu braucht man manchmal das Systempaket python3-venv).

# Umgebung im Ordner .venv anlegen
python -m venv .venv

# aktivieren: Linux und macOS
source .venv/bin/activate
# aktivieren: Windows PowerShell
.venv\Scripts\Activate.ps1

# jetzt installiert pip Pakete in .venv
python -m pip install requests
python -c "import sys; print(sys.prefix)"

# Umgebung verlassen
deactivate

Nach der Aktivierung erscheint am Anfang der Terminalzeile (.venv). Den Ordner der Umgebung committen Sie nicht in git (tragen Sie .venv/ in die .gitignore ein) und Sie kopieren ihn auch nicht auf andere Rechner. Stattdessen halten Sie die Liste der Abhängigkeiten fest und erstellen die Umgebung neu. Verbietet PowerShell das Starten des Aktivierungsskripts, erlauben Sie es für den Benutzer: Set-ExecutionPolicy -Scope CurrentUser RemoteSigned.

uv und pyproject.toml

Moderne Projekte beschreiben ihre Abhängigkeiten in pyproject.toml. Der Manager uv, der im Kurs verwendet wird, verbindet das Erstellen der Umgebung und die Installation: uv add pandas lädt das Paket herunter, trägt es in pyproject.toml ein und hält die genauen Versionen in uv.lock fest. Ein Kollege klont das Projekt, führt uv sync aus und hat eine identische Umgebung.

[project]
name = "expenses"
version = "0.1.0"
requires-python = ">=3.15"
dependencies = [
    "pandas>=2.3",
]

[project.scripts]
expenses = "expenses.cli:main"

Lazy imports in Python 3.15 (PEP 810)

Die wichtigste Neuerung von Python 3.15 in diesem Thema ist das Schlüsselwort lazy. Schwere Bibliotheken laden lange: In der Messung des Kurses mit dem Image python:3.15-slim dauerte ein gewöhnlicher import pandas rund 415 ms, lazy import pandas nur rund 13 ms. Für ein Kommandozeilenprogramm, das man für --help startet, ist der Unterschied enorm.

lazy import pandas as pd
lazy from expenses.report import build_report

def main() -> None:
    ...
    df = pd.read_csv(path)   # hier wird pandas tatsächlich geladen

Statt des Moduls wird ein Stellvertreterobjekt (types.LazyImportType) an den Namen gebunden, und der echte Import erfolgt beim ersten Zugriff auf den Namen. Kommt es dazu nie, entsteht überhaupt kein Zeitaufwand.

Einschränkungen des lazy import

• Nur auf der obersten Ebene eines Moduls erlaubt: innerhalb einer Funktion, Klasse oder eines try/except gibt es einen SyntaxError.
• lazy from x import * ist verboten.
• ModuleNotFoundError erscheint nicht beim Start, sondern erst bei der ersten Verwendung.
• Nebenwirkungen eines Moduls (Registrierung von Plugins und Ähnliches) verschieben sich in der Zeit.

Alle Importe auf einmal lazy zu machen geht mit dem Schalter -X lazy_imports=all oder der Umgebungsvariablen PYTHON_LAZY_IMPORTS=all. Ausnahmen legen Sie über sys.set_lazy_imports_filter() fest. Für Code, der auch auf älteren Versionen laufen soll, gibt es die Modulvariable __lazy_modules__ = ["pandas"]: Python 3.15 macht die genannten Importe lazy, ältere Versionen führen einfach einen normalen import aus. Wo beim Start Zeit verloren geht, zeigt python -X importtime -c "import pandas". Am meisten profitieren Programme mit häufigen kurzen Starts, ein langlebiger Server gewinnt kaum etwas.

Typische Fehler

• ModuleNotFoundError: No module named 'requests' — die Bibliothek ist in einem anderen Python installiert, oder die Umgebung ist nicht aktiviert. Prüfen Sie mit python -m pip show requests mit demselben Interpreter.
• Die eigene Datei heißt json.py, random.py oder csv.py — der Ordner des Skripts steht in sys.path an erster Stelle und verdeckt das Standardmodul. Python 3.13+ gibt im Fehlertext den Hinweis „consider renaming“. Benennen Sie die Datei um und löschen Sie __pycache__.
• Zirkulärer Import: a.py importiert b.py, und b.py importiert a.py. Lagern Sie das Gemeinsame in ein drittes Modul aus oder importieren Sie innerhalb einer Funktion.
• pip wird im Interpreter aufgerufen (>>> pip install) — das ergibt einen SyntaxError. Pip-Befehle führen Sie im Terminal aus.

Fazit

Ein Modul ist eine Datei, ein Paket ein Ordner mit Modulen, eine Bibliothek ein fertiger Satz davon. import sucht das Modul im Cache und über sys.path und führt es einmal aus. Fremde Bibliotheken installieren Sie mit pip oder uv nur in eine virtuelle Umgebung (venv). So stören sich Projekte nicht, und die Umgebung lässt sich leicht wiederherstellen. Im Python-Kurs wird das Thema praktisch behandelt: Der Ausgabentracker wird zu einem Paket mit Abhängigkeiten, und lazy imports sorgen für einen schnellen Start.