Die Struktur eines Python-Projekts

von

Ein Python-Projekt mag am Anfang nur aus ein oder zwei Dateien bestehen. Über eine Projektstruktur muss man sich in diesem Fall keine Gedanken machen. Anders sieht es aber aus, wenn das Programm wächst. Neben den eigentlichen Python-Dateien könnte irgendwann auch noch eine Dokumentation dazukommen. Und in der Regel sollen die Tests in separaten Dateien und einem eigens dafür vorgesehenen Verzeichnis gespeichert werden. Es stellt sich dann zwangsläufig die Frage nach einer sinnvollen Struktur.

Diese Frage ist nicht einfach zu beantworten. Denn im Internet sowie der einschlägigen Fachliteratur finden sich dazu unterschiedliche Vorschläge. Mit anderen Worten: Es gibt nicht die Projektstruktur. So sind die nachfolgenden Ausführungen ebenfalls nur als Vorschlag zu verstehen.

Eine einfache Projektstruktur

Eine typische Struktur für ein Projekt mit dem Namen „my_project“ könnte folgendermaßen aussehen:

.
├── README.md
├── docs
├── my_project
│   ├── __init__.py
│   └── main.py
├── pyproject.toml
├── pytest.ini
├── requirements-dev.txt
├── requirements.txt
├── setup.cfg
├── setup.py
└── tests
    └── __init__.py

Innerhalb des Projekts „my_project“ befinden sich drei Unterordner:

  • my_project: Dieser Ordner hat (hier) die gleiche Bezeichnung wie das Projekt. Anstelle des Projektnamens verwenden manche Entwickler einen Ordner mit der Bezeichnung src. Bei dem Verzeichnis my_project handelt sich um ein Paket (Package), weswegen dieser Ordner eine Datei namens __init__.py enthält. Diese Datei ist (heutzutage) in der Regel leer. Sie wird aufgerufen, wenn ein Modul dieses Pakets importiert wird.
  • docs: In diesem Verzeichnis befinden sich alle notwendigen Dateien für die Dokumentation (z.B. für den Dokumentations-Generator Sphinx).
  • tests: Hier befinden sich alle Dateien, die Tests enthalten. Auch dieses Verzeichnis hat eine Datei mit dem Namen __init__.py. Sofern als Test-Framework pytest verwendet wird, kann im Projektordner noch optional eine Konfigurationsdatei für pytest dazukommen: pytest.ini.

Die für dieses Projekt erforderlichen externen Bibliotheken, zum Beispiel numpy oder matplotlib werden in der Datei requirements.txt aufgeführt. Sie können dann mit pip wie folgt installiert werden:

pip3 install -r requirements.txt # Linux, macOS
pip install -r requirements.txt  # Windows

Manche Entwickler lagern jene Pakete, die nicht unmittelbar für die Ausführung dieses Projekts erforderlich sind, in eine Datei namens requirements-dev.txt aus (z.B. könnte man pytest in dieser Datei aufführen). Dies ist jedoch optional.

Damit bleiben noch die Dateien pyproject.toml, setup.py und setup.cfg. Heutzutage wird nur noch die Datei pyproject.toml benötigt. Sie enthält alle Metadaten zum Projekt. Da ihr auch älteren Programmen begegnen könnt, habe ich der Vollständigkeit halber auch die Dateien setup.py und setup.cfg aufgeführt. Aber wie gesagt, benötigt werden sie nicht mehr. Nichtsdestotrotz möchte ich zunächst auf diese älteren Dateien eingehen.

setup.py und setup.cfg

Früher existierte nur eine Datei mit dem Namen setup.py. Falls nur diese Datei (und nicht auch noch setup.cfg) verwendet wird, enthält sie die Metadaten zum Projekt. Für unser Beispielprojekt könnte sie folgenden Inhalt haben:

from setuptools import setup, find_packages

VERSION = '0.1.0'

setup(
    name='my_project',
    version=VERSION,
    license='MIT',
    description='Just an example.',
    author='My Name',
    author_email='my_name@xyz.com',
    url='https://github.com/<user>/<project>',
    packages=find_packages(exclude=('tests', 'docs')),
    python_requires='>=3.8'
)

Die Datei setup.py kann recht komplex werden. Deswegen wurde die Konfigurationsdatei setup.cfg eingeführt, die die erforderlichen Metadaten enthält. Wird setup.cfg verwendet, dann reduziert sich der Inhalt von setup.py auf zwei Zeilen:

import setuptools

setuptools.setup()

Und setup.cfg könnte folgenden Inhalt haben:

[metadata]
name = my_project
author = 
author-email = 
license =
long_description = file: README.md
url = https://
requires-python = >= 3.8

Die Datei pyproject.toml

Kommen wir nun zur pyproject.toml. Sie reicht heutzutage als Konfigurationsdatei aus. Diese Datei ermöglicht durch die Anagbe des Build-Systems das Erstellen eines Installations-Pakets. Damit wird es möglich, ein Python-Programm auf der Plattform pypi.org zu veröffentlichen (so dass eine Installation mit dem Befehl pip möglich ist).

Es ist denkbar, dass ihr auf Projekte stoßt, die sowohl die Datei pyproject.toml als auch die Datei setup.cfg haben. Die Datei pyproject.toml enthält in diesem Fall grundsätzlich nur die Informationen zum zu verwendenden Build-System. Für das Erstellen eines Python-Pakets mit setuptools sind folgende Zeilen zur Datei pyproject.toml hinzuzufügen:

[build-system]
requires = ["setuptools >= 77.0.3"]
build-backend = "setuptools.build_meta"

Anstelle von setuptools, können auch Hatchling, Flip, PDM oder uv-build verwendet werden. Falls ihr wissen möchtet, welche Informationen zum jeweiligen Build-System in der Datei pyproject.toml enthalten sein müssen, hilft euch der Python Packagin User Guide weiter.

Die Angaben zum Build-System stehen also in der Datei pyproject.toml, die Datei setup.cfg enthält die übrigen Metadaten. Hier ein Beispiel:

[metadata]
name = my_project
version = 1.0.0
author = Abcde
author_email = abcde@xyz.com
url = https://...
description = ...
long_description = file: README.md
long_description_content_type = text/markdown
license = MIT
license_file = LICENSE
requires_python = >=3.13
classifiers =
    Intended Audience :: Developers
    Development Status :: 4 - Beta
    License :: OSI Approved :: MIT License
    Operating System :: MacOS
    Programming Language :: Python :: 3
    Programming Language :: Python :: 3.13
    Programming Language :: Python :: 3.14
    Programming Language :: Python :: Implementation :: CPython

Es ist aber auch möglich alle Metadaten in die Datei pyproject.toml zu schreiben, so dass setup.cfg weggelassen werden kann. Dieser Weg ist bei neuen Projekten zu bevorzugen. Hier ein Beispiel:

[build-system]
requires = ["setuptools>=70.0"]
build-backend = "setuptools.build_meta"

[project]
name = "my_project"
version = "1.0.0"
description = "Project description"
readme = "README.md"
requires-python = ">=3.12"
license = { text = "MIT" }
authors = [
    { name = "Your Name", email = "name@xyz.com" }
]
urls = {"Homepage" = "https://github.com/username/project_name"}

classifiers = [
    "License :: OSI Approved :: MIT License",
    "Operating System :: OS Independent",
    "Programming Language :: Python :: 3",
    "Programming Language :: Python :: 3.12",
    "Programming Language :: Python :: 3.13",
    "Programming Language :: Python :: 3.14",
    "Programming Language :: Python :: Implementation :: CPython"
]

Ergänzende Hinweise

Die Datei main.py stellt den Einstiegspunkt des Programms dar. Die Bezeichnung kann frei gewählt werden, aber häufig heißt diese Datei main.py oder cli.py (wenn es sich um ein Konsolenprogramm handelt).

Es ist eine gute Idee, zu jedem Projekt eine README.md hinzuzufügen. Spätestens wenn ein Projekt veröffentlicht wird, ist so eine Datei erforderlich und bietet Dritten eine Orientierung. Ergänzend findet sich in Projekten (bei Github, GitLab, etc.) häufig auch eine CONTRIBUTING.md, die anderen Entwicklern Hinweise zur Teilnahme am Projekt bietet.

Werft bei Python-Projekten auf Github einen Blick auf die Dateien setup.py, setup.cfg und pyproject.toml. So erhaltet Ihr einen Eindruck davon, welche Metadaten andere Entwickler hinzugefügt haben.

Der Ordner „tests“ befindet sich in diesem Beispiel in der obersten Verzeichnisebene. Manche Entwickler bevorzugen es jedoch, dieses Verzeichnis als Unterverzeichnis zum Paketverzeichnis anzulegen.

Auf Github findet Ihr ein Shellskript, das ihr dafür verwenden könnt, automatisch ein Projekt-Grundgerüst zu erstellen. Dieses Skript erhebt keinen Anspruch auf Vollständigkeit. Es mag für auch aber ein guter Ausgangspunkt für ein eigenes Skript sein.

Im Internet finden sich weitere gute Beispiele zur Projektstruktur, zum Beispiel im Artikel „Ultimate Setup for Your Next Python Project“, der auch Beispiele zu den Konfigurationsdateien enthält.

Eine Übersicht zu weiteren Artikeln zur Programmiersprache Python findest Du auf dieser Seite.

Zuletzt aktualisiert am 29. Dezember 2025