nbdev3: Konfiguration wechselt von settings.ini zu pyproject.toml
Erstellen Sie mit Jupyter Notebooks ansprechende Software. Dokumente unterstützen LaTeX, sind durchsuchbar und werden automatisch mit Hyperlinks versehen (einschließlich sofort einsatzbereiter Unterstützung für viele Pakete über nbdev-index). Veröffentlichen Sie Pakete auf PyPI und Conda sowie Tools zur Vereinfachung der Paketfreigabe.
Auf einen Blick
- Was ist das?
- Ein Blick auf AnswerDotAI/nbdev: der Umzug der Konfiguration unter PEP 621, der Zwei-Wege-Sync zwischen Notebook und Modul, Quarto-Dokumentation und die Grenzen unter Windows.
- Für wen ist es gedacht?
- Sinnvoll ist nbdev für Pakete, deren Code ohnehin in Notebooks entsteht und die Dokumentation, Tests und Releases aus einem Bestand ziehen wollen, auf macOS, Linux oder Windows mit WSL. Wenig gewonnen ist bei Paketen, die vor allem aus Typdefinitionen bestehen, oder bei Teams, die ohne WSL unter cmd oder PowerShell arbeiten.
- Darf ich es kommerziell nutzen?
- Ja. Apache-2.0 ist eine freizügige Lizenz: Sie dürfen darauf aufbauende Software nutzen, verändern und verkaufen, solange Sie die Urheberrechts- und Lizenzhinweise beibehalten.
- Wird es noch gepflegt?
- Ja. Die letzten Commits kamen vor 2 Tagen.
- In welcher Sprache ist es geschrieben?
- Hauptsächlich Jupyter Notebook, laut der Sprachstatistik von GitHub.
Die Antworten beruhen auf den GitHub-Daten des Projekts (zuletzt abgeglichen am 14. September 2026) und auf unserer Analyse. Sie sind keine Rechtsberatung.
TIEFGEHENDE OPEN-SOURCE-ANALYSE
nbdev3 verlagert die Konfiguration nach pyproject.toml
Im Januar 2026 erschien nbdev3, und der Bruch sitzt an einer Stelle, die jedes bestehende Projekt betrifft: Die Konfiguration wandert von `settings.ini` nach `pyproject.toml`. Das folgt PEP 621 und teilt die Datei in zwei Bereiche. Projektmetadaten stehen künftig im Standardabschnitt `[project]`, während die nbdev-spezifischen Einstellungen in `[tool.nbdev]` gehören.
Wer von nbdev2 kommt, muss nicht von Hand umschreiben. Das README nennt `nbdev-migrate-config`, ausgeführt im Wurzelverzeichnis des Projekts. Das Kommando überführt `settings.ini` in eine `pyproject.toml` und hebt die GitHub-Actions-Workflows auf nbdev3-taugliche Versionen. Notebooks und vorhandener Code bleiben laut README unverändert.
Trotzdem bleibt bei gewachsenen Projekten eine Prüfung: Schlüssel, die vorher nur nbdev kannte, stehen jetzt in `[project]`, und dort gelten die Regeln des Python-Packagings statt der nbdev-Konventionen. `nbdev-create-config` legt für neue Projekte eine passende `pyproject.toml` an, `nbdev-requirements` schreibt daraus eine `requirements.txt`.
Quarto-Dokumentation und nbdev-index als Verweisschicht
Die Dokumentation entsteht bei nbdev als Nebeneffekt des Notebooks. Leichtgewichtige Markierung in den Zellen genügt, und `nbdev-docs` erzeugt daraus eine Seite mit Quarto, gehostet über GitHub Pages. LaTeX wird unterstützt, die Seiten sind durchsuchbar, und Verweise auf fremde Pakete werden automatisch verlinkt. Für letzteres nennt das README `nbdev-index`, einen eigenen Index, der viele Pakete ohne weiteres Zutun abdeckt.
Der Anspruch dahinter ist pragmatisch: Dokumentation und Tests sind gleichrangig mit dem Code, weil beides in denselben Zellen steht. `nbdev-readme` erzeugt die README.md aus einem Notebook, standardmäßig aus `index.ipynb`, sodass auch die Startseite des Repositorys aus demselben Bestand kommt. Für die Navigation entsteht mit `nbdev-sidebar` eine `sidebar.yml`.
Wer nur eine ansehnliche Seite will und auf den Export von Modulen verzichten kann, fährt mit Quarto allein. Quarto rendert Notebooks ebenfalls, kennt aber keinen Rückweg: Änderungen am erzeugten Python-Modul landen nicht automatisch wieder im Notebook.
nbdev-export und nbdev-update: Zwei-Wege-Sync mit Zell-IDs
Der Kern von nbdev ist die Synchronisation zwischen Notebook und Klartext in beide Richtungen. `nbdev-export` schreibt die markierten Zellen als Python-Module heraus, `nbdev-update` trägt Änderungen, die in der IDE am Modul gemacht wurden, zurück ins Notebook. Damit das an der richtigen Stelle landet, wird jede exportierte Zelle mit der eindeutigen ID ihrer Notebook-Zelle markiert. Das README nennt dieses Verfahren ausdrücklich robust, weil `nbdev-update` so immer die zugehörige Zelle trifft.
Eine Regel aus der FAQ beschneidet die Freiheit bei der Zellgestaltung. Werden Importe und Berechnungen gemischt, meldet nbdev die Warnung, dass eine Zelle eine Mischung aus Imports und Berechnungen enthalte. Betroffen sind Zellen, die nicht exportiert werden und dennoch `import`-Anweisungen neben anderem Code tragen.
Die Ausnahmen sind im README benannt: `try: import`-Blöcke und Importe innerhalb von Funktionsdefinitionen bleiben zulässig, nur Anweisungen auf oberster Ebene zählen. Als Grund gibt das README die Dokumentationserzeugung an, nicht den Exportvorgang selbst. Diese Einschränkung ist ein gutes Beispiel dafür, wie nbdev Schreibweisen vorschreibt, die reines Python nicht verlangt.
nbdev-test, nbdev-prepare und die GitHub-Actions-Voreinstellung
Tests sind bei nbdev gewöhnliche Notebook-Zellen und laufen mit einem einzigen Kommando parallel: `nbdev-test`, gefolgt von einem Pfadmuster und optionalen Flags. Das unterscheidet den Notebook-Ansatz vom klassischen Projekt. Es gibt keine separate Testsuite, die nebenher gepflegt werden muss, sondern Zellen, die ohnehin geschrieben wurden, um ein Verhalten zu zeigen.
`nbdev-prepare` bündelt den üblichen Ablauf: exportieren, testen, Notebooks bereinigen und bei Bedarf die README rendern. Für die Freigabe stehen `nbdev-pypi`, `nbdev-conda` und `nbdev-release-both` bereit; `nbdev-release-gh` erzeugt über `nbdev-changelog` ein CHANGELOG.md aus geschlossenen und gelabelten Issues, lässt es bearbeiten und stößt danach den Release an.
Continuous Integration über GitHub Actions ist vorkonfiguriert und führt Tests sowie den Neuaufbau der Dokumentation aus. Für Veröffentlichungen gilt die Python-Konvention, dass nur exportierte Objekte in `__all__` landen; nbdev setzt das laut README selbst durch.
Installation von nbdev: pip, WSL und die Umgebungsregel
Die Installation ist eine Zeile: `pip install nbdev`. Zwei Einschränkungen wiegen schwerer, als diese Zeile vermuten lässt. Erstens muss nbdev in dieselbe Python-Umgebung installiert werden, die auch Jupyter und das eigene Projekt nutzen; getrennte Umgebungen sind laut README nicht vorgesehen. Zweitens läuft nbdev auf macOS, Linux und den meisten unixartigen Systemen, unter Windows ausschließlich innerhalb von WSL, ausdrücklich nicht in cmd oder PowerShell.
Wer wissen will, welche Kommandos bereitstehen, ruft `nbdev-help` auf. Die Liste reicht von `nbdev-new` über `nbdev-install-quarto` und `nbdev-install-hooks` bis zu `nbdev-fix`, das aus einem Notebook mit Merge-Konflikten wieder eine arbeitsfähige Datei macht, und `nbdev-merge`, einem Merge-Treiber für Git. `nbdev-migrate` überführt Markdown- und Notebook-Dateien von v1 nach v2.
Die Git- und Jupyter-Hooks bereinigen unerwünschte Metadaten und stellen Konflikte in lesbarer Form dar, was den Umgang mit Notebooks in Versionsverwaltung spürbar entschärft.
Apache-2.0, Versionsstand 3.3.13 und ein Gegenbeispiel
Das Repository steht unter Apache-2.0, die Dokumentation liegt auf nbdev.fast.ai, und der letzte erfasste Release ist 3.3.13 vom 25. August 2026, nach 3.3.12 vom 12. August und 3.3.11 vom 10. August. Die Zähler nennen 5.314 Sterne, 517 Forks und 186 offene Issues, was auf breite Nutzung bei gleichzeitig gut gefüllter Warteschlange hindeutet.
Ein konkretes Gegenbeispiel zum Notebook-Ansatz: Ein Paket, das überwiegend aus Typdefinitionen und Konfigurationsklassen besteht, gewinnt durch Notebooks wenig und verliert die gewohnte IDE-Navigation, solange der Sync nicht eingerichtet ist. Auch ein Team, das unter Windows ohne WSL entwickelt, ist von vornherein ausgeschlossen.
Klären lässt sich die Eignung in drei Schritten: `pip install "nbdev==3.3.13"` in der Jupyter-Umgebung, danach `nbdev-new` für ein Gerüstprojekt und `nbdev-test` auf dessen Notebooks. Bleibt `nbdev-export` ohne Ausgabe, liegt das Problem an der Umgebung, nicht am Projekt.
Redaktionelles Fazit
Sinnvoll ist nbdev für Pakete, deren Code ohnehin in Notebooks entsteht und die Dokumentation, Tests und Releases aus einem Bestand ziehen wollen, auf macOS, Linux oder Windows mit WSL. Wenig gewonnen ist bei Paketen, die vor allem aus Typdefinitionen bestehen, oder bei Teams, die ohne WSL unter cmd oder PowerShell arbeiten. Geprüft werden sollte zuerst, ob nbdev in derselben Umgebung liegt wie Jupyter und das Projekt: pip install "nbdev==3.3.13", dann nbdev-new und nbdev-test auf dem Gerüstprojekt.
Community-Notizen