So beheben Sie ImportError: Versuch eines relativen Imports ohne bekanntes übergeordnetes Paket

Der FehlerImportError: Relativer Importversuch ohne bekanntes übergeordnetes Paket in Python verwirrt viele Entwickler. Dies geschieht, wenn Sie eine Datei, die relative Importe verwendet, als Skript und nicht als Teil eines Pakets ausführen. Hier erfahren Sie, warum es passiert und wie Sie es beheben können.

Warum das passiert

Relative Importe (from .module import x) funktionieren nur, wenn Python weiß, dass die Datei Teil eines Pakets ist. Wenn Sie eine Datei direkt ausführen (python myfile.py), behandelt Python sie als Skript der obersten Ebene ohne übergeordnetes Paket – relative Importe schlagen daher fehl. Das. im Import gibt es kein Paket, auf das man sich beziehen kann.

Das Setup, das es auslöst

# Project structure
myproject/
├── mypackage/
│   ├── __init__.py
│   ├── main.py
│   └── helper.py

# main.py uses a relative import
# from .helper import do_something

# 🐛 Running directly fails
python mypackage/main.py
# ImportError: attempted relative import with no known parent package

Fix 1: Als Modul mit -m

# Run from the PROJECT ROOT (parent of mypackage) using -m
cd myproject
python -m mypackage.main

# The -m flag runs it as a module within the package,
# so Python knows the parent package and relative imports work

ausführen Dies ist die richtige Methode zum Ausführen von Paketcode, der relative Importe verwendet. Beachten Sie, dass Sie vom Projektstamm aus ausführen und Punkte und keine Schrägstriche verwenden.

Fix 2: Absolute Importe verwenden

# Instead of relative imports:
# from .helper import do_something          # relative

# Use absolute imports:
from mypackage.helper import do_something   # absolute

# Absolute imports work whether run as a script or module,
# as long as the package is on the Python path

Lösung 3: Fügen Sie einen geeigneten Einstiegspunkt hinzu

# Create a run script at the project root (outside the package)
# myproject/run.py
from mypackage.main import main

if __name__ == '__main__':
    main()

# Run it from the root — absolute imports resolve correctly
python run.py

Fix 4: Machen Sie daraus ein ordnungsgemäß installierbares Paket

# pyproject.toml
[project]
name = "mypackage"
version = "0.1.0"

[project.scripts]
mypackage = "mypackage.main:main"

# Install in editable mode
pip install -e .

# Now run via the entry point — imports work correctly
mypackage
# Or: python -m mypackage.main

Relative vs. absolute Importe verstehen

# Relative imports (need a parent package)
from . import sibling_module        # same package
from .helper import func            # module in same package
from ..other_package import thing   # parent package

# Absolute imports (need package on path)
from mypackage.helper import func
from mypackage.subpackage.mod import thing

# Rule of thumb: absolute imports are more explicit and robust.
# Use them unless you have a specific reason for relative imports.

Die __init__.py-Anforderung

# For a directory to be a package (enabling relative imports),
# it typically needs an __init__.py file:

mypackage/
├── __init__.py       # makes mypackage a package (can be empty)
├── main.py
└── helper.py

# Without __init__.py, Python may treat it as a namespace package
# (works in modern Python but can cause confusion). For clarity,
# include __init__.py in packages that use relative imports.

Kurzanleitung zur Entscheidungsfindung

• Eine Paketdatei für die Entwicklung ausführen? Verwenden Siepython -m package.module aus dem Projektstamm
• Möchten Sie Importe, die immer funktionieren? Verwenden Sie absolute Importe (from mypackage.x import y)
• Erstellen Sie ein echtes Projekt?Machen Sie es zu einem installierbaren Paket mit einem Einstiegspunkt
• Nur ein einfaches Skript?Verwenden Sie keine relativen Importe – verwenden Sie absolute Importe oder packen Sie alles in eine Datei

Häufig gestellte Fragen

F: Warum funktionieren relative Importe in einigen Dateien, aber nicht in anderen?
A: Sie funktionieren, wenn die Datei als Teil eines Pakets importiert wird, schlagen jedoch fehl, wenn sie direkt als Skript ausgeführt werden. Das Gleiche file can work when imported and fail when run with python file.py — because direct execution has no parent package.

Q: Should I use relative or absolute imports?
A: Absolute imports are generally recommended — they’re explicit, work in more situations, and are clearer about where things come from. Use relative imports only within a package when it improves readability, and understand they require running as a module.

Q: What does the -m flag actually do?
A: It runs a module as part of its package, setting up the package context so relative imports resolve. python -m mypackage.main tells Python “run main as a module inside mypackage,” giving it the parent package it needs.

Q: Do I always need __init__.py?
A: In modern Python, namespace packages work without it, but including __init__.py makes your package explicit and avoids ambiguity, especially when using relative imports. It’s good practice to include it.

Q: My IDE runs it fine but the terminal fails. Why?
A: IDEs often set the working directory and Python path to the project root and may run files as modules. Replicate that in the terminal: run from the project root with python -m package.module, or configure your path/entry point to match.

Conclusion

“Attempted relative import with no known parent package” means you’re running a package file directly as a script, so relative imports Sie haben kein übergeordnetes Paket zum Auflösen. Führen Sie es als Modul mitaus, oder erstellen Sie einen geeigneten Einstiegspunkt im Projektstamm Bevorzugen Sie im Allgemeinen absolute Importe – sie sind explizit und funktionieren.python -m mypackage.mainaus, oder erstellen Sie einen geeigneten Einstiegspunkt im Projektstamm Bevorzugen Sie im Allgemeinen absolute Importe – sie sind explizit und funktionieren.from mypackage.helper import xaus, oder erstellen Sie einen geeigneten Einstiegspunkt im Projektstamm Bevorzugen Sie im Allgemeinen absolute Importe – sie sind explizit und funktionieren.aus, oder erstellen Sie einen geeigneten Einstiegspunkt im Projektstamm Bevorzugen Sie im Allgemeinen absolute Importe – sie sind explizit und funktionieren.