nbdev : un environnement de développement piloté par les notebooks Jupyter
Créez un logiciel délicieux avec Jupyter Notebooks. Les documents prennent en charge LaTeX, sont consultables et sont automatiquement liés par des hyperliens (y compris la prise en charge prête à l'emploi de nombreux packages via nbdev-index). Publiez des packages sur PyPI et conda ainsi que des outils pour simplifier les versions de packages.
En bref
- De quoi s’agit-il ?
- Plateforme open-source sous Apache-2.0 qui génère documentation, tests, CI et empaquetage PyPI/conda à partir de notebooks, avec configuration désormais dans pyproject.toml (v3).
- À qui s’adresse-t-il ?
- nbdev convient aux développeurs Python cherchant à unifier documentation et code dans un seul artefact, particulièrement pour les projets de machine learning et les bibliothèques scientifiques. Avant migration vers v3, vérifiez les configurations WSL sous Windows, la compatibilité des hooks Jupyter/git et l'accès aux droits root pour l'installation de Quarto.
- Puis-je l’utiliser commercialement ?
- Oui. Apache-2.0 est une licence permissive : vous pouvez utiliser, modifier et vendre un logiciel qui en dépend, à condition de conserver les mentions de droit d’auteur et de licence.
- Est-il encore maintenu ?
- Oui. Les derniers commits datent d’il y a 2 jours.
- En quel langage est-il écrit ?
- Principalement Jupyter Notebook, d’après les statistiques de langage de GitHub.
Ces réponses reposent sur les données GitHub du projet (dernière synchronisation le 14 septembre 2026) et sur notre analyse. Elles ne constituent pas un avis juridique.
ANALYSE OPEN SOURCE APPROFONDIE
Une plateforme de développement centrée sur les notebooks
nbdev est un environnement de développement piloté par les notebooks Jupyter. Le README pose le problème fondamental : le débogage et le refactorage sont plus simples lorsque les objets vivants restent disponibles, ce qui n'est pas le cas dans les éditeurs traditionnels. nbdev accélère cette boucle en tissant les tests et la documentation directement dans le flux de développement des notebooks. Le dépôt affiche 5 314 étoiles et 517 forks, et le README cite une utilisation sur trois ans incluant des bibliothèques de deep learning, des clients d'API, des extensions du langage Python et des interfaces de terminal. Cette adoption étendue suggère une certaine maturité, bien que le README ne chiffre pas les performances brutes ni le temps de construction.
L'évolution v3 : configuration centralisée dans pyproject.toml
La version 3, sortie en janvier 2026, marque un changement architectural majeur. La configuration passe de settings.ini à pyproject.toml, conformément à la PEP 621. Les métadonnées du projet résideny dans [project], tandis que les réglages nbdev-spécifiques vont dans [tool.nbdev]. Le README propose un chemin d'migration automatisé : lancer nbdev-migrate-config à la racine du projet converti settings.ini en pyproject.toml et met à jour les workflows GitHub Actions vers des versions compatibles v3. Selon le README, les notebooks et le code existants n'ont besoin d'aucune modification. Cette approche réduit les points de configuration et abaisse la friction pour les nouveaux utilisateurs habitués à l'écosystème Python moderne.
Génération de documentation avec Quarto et hyperliaison automatique
La documentation est construite automatiquement avec Quarto et déployée sur GitHub Pages. Les résultats prennent en charge LaTeX, la recherche, et les hyperliens automatiques, y compris via l'extension nbdev-index qui active le cross-linking pour les paquets tiers courants. Le pipeline comprend nbdev-docs pour créer la Quarto et le README.md, nbdev-preview pour prévisualiser en local, et nbdev-install-quarto pour installer la dernière version de Quarto sur macOS/Linux ou afficher les instructions pour Windows. L'installation automatique de Quarto peut exiger les droits root sur Unix ; le README signale ce comportement mais ne propose qu'un chemin d'installation sans root pour les utilisateurs Linux soucieux des permissions.
Tests parallélisés et intégration continue intégrée
Les tests sont écrits comme des cellules normales dans les notebooks et s'exécutent en parallèle via nbdev-test. L'intégration continue est fournie via GitHub Actions, qui lance les tests et reconstruit la documentation à chaque push. Le README documente les commandes nbdev-prepare (exporte, teste et nettoie les notebooks), nbdev-test (paralelise sur les notebooks correspondant à un motif), et nbdev-changelog (génère un CHANGELOG.md depuis les issues fermées et étiquetées). Aucun benchmark n'est fourni dans le README concernant les temps de construction ou les résultats de performance ; ces métriques doivent être validées empiriquement dans l'environnement du projet utilisateur.
Synchronisation bidirectionnelle et gestion des conflits de fusion
Le système de deux-sens entre notebooks et code source en texte brut permet d'utiliser un IDE pour naviguer ou modifier rapidement le code. Chaque cellule exportée porte un identifiant de cellule unique, ce qui garantit que nbdev-update cible toujours la bonne cellule. Les hooks Git natifs (via nbdev-install-hooks) éliminent les métadonnées indésirables et rendent les conflits de fusion lisibles plutôt que de présenter du JSON brut. Les commandes du pipeline incluent nbdev-clean (nettoie tous les notebooks), nbdev-fix (reconstitue un notebook en conflit), nbdev-merge (utilisé comme pilote de fusion Git), et nbdev-update (propage les changements des modules aux notebooks générateurs). Cette infrastructure réduit les frictions usuelles du co-développement.
Surface de ligne de commande et empaquetage PyPI/conda
nbdev-help énumère 36 scripts de console couvrant le cycle de vie complet. Pour la publication, nbdev-pypi crée et téléverse un paquet sur PyPI, nbdev-conda crée un meta.yaml pour conda, et nbdev-release-both automatise les deux. nbdev-requirements génère un requirements.txt à partir de pyproject.toml. Les exportations suivent les bonnes pratiques Python : seuls les objets étiquetés export sont inclus dans __all__, et les métadonnées du paquet sont synthétisées à partir des sections [project] et [tool.nbdev]. Le README spécifie aussi nbdev-new pour initialiser un projet et nbdev-create-config pour générer une configuration vierge. Aucun détail n'est fourni sur les drapeaux d'emballage avancés ou les options de signature de paquets.
Compatibilité platforme et installation
nbdev s'installe via pip install nbdev et fonctionne sur macOS, Linux et systèmes Unix. Sous Windows, WSL est requis ; cmd et Powershell ne sont pas pris en charge. Le README insiste : nbdev doit partager l'environnement Python de Jupyter et du projet. Le dépôt compte 186 problèmes ouverts, indiquant un flux de travail de maintenance ; le README ne promet aucun délai de réponse ni engagement de support. La page d'accueil est https://nbdev.fast.ai/. Le projet est sous licence Apache-2.0, copyright fast.ai, Inc. depuis 2019, avec clause de brevet standard.
FAQ sur les imports, Quarto et bonnes pratiques
Le FAQ aborde deux points clés. D'abord, un avertissement sur les cellules qui mélangent imports et calculs : lors de la génération de documentation, nbdev exécute les imports, les cellules marquées export et les appels show_doc. Mélanger importations et code dans une seule cellule ralentit ou casse le pipeline. Seules les instructions de niveau supérieur posent problème ; les blocs try: import et les imports dans les fonctions sont acceptables. Deuxièmement, l'installation de Quarto peut exiger les droits root sur Unix. Le README fournit un chemin d'installation sans root pour Linux. Ces notes révèlent des angles morts de l'expérience utilisateur dont l'absence de documentation complète invite à des essais empiriques.
Conclusion éditoriale
nbdev convient aux développeurs Python cherchant à unifier documentation et code dans un seul artefact, particulièrement pour les projets de machine learning et les bibliothèques scientifiques. Avant migration vers v3, vérifiez les configurations WSL sous Windows, la compatibilité des hooks Jupyter/git et l'accès aux droits root pour l'installation de Quarto.
Notes de la communauté