Metadata-Version: 2.4
Name: nbdev
Version: 3.2.1
Summary: Create delightful software with Jupyter Notebooks
Author-email: "Jeremy Howard and the fast.ai community" <j@fast.ai>
License: Apache-2.0
Project-URL: Repository, https://github.com/AnswerDotAI/nbdev
Project-URL: Documentation, https://nbdev.fast.ai/
Keywords: nbdev,fastai,jupyter,notebook,export
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Natural Language :: English
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: License :: OSI Approved :: Apache Software License
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: fastcore>=1.14.6
Requires-Dist: execnb>=0.2.4
Requires-Dist: astunparse
Requires-Dist: ghapi>=2.0.0
Requires-Dist: watchdog
Requires-Dist: asttokens
Requires-Dist: setuptools
Requires-Dist: build
Requires-Dist: fastgit
Requires-Dist: pyyaml
Requires-Dist: tomli; python_version < "3.11"
Provides-Extra: dev
Requires-Dist: ipywidgets; extra == "dev"
Requires-Dist: nbdev-numpy; extra == "dev"
Requires-Dist: nbdev-stdlib; extra == "dev"
Requires-Dist: pandas; extra == "dev"
Requires-Dist: matplotlib; extra == "dev"
Requires-Dist: black; extra == "dev"
Requires-Dist: svg.py; extra == "dev"
Requires-Dist: nbclassic; extra == "dev"
Requires-Dist: pysym2md>=0.0.6; extra == "dev"
Requires-Dist: llms-txt; extra == "dev"
Requires-Dist: sphinx; extra == "dev"
Requires-Dist: plum-dispatch; extra == "dev"
Dynamic: license-file

# Getting Started


<!-- WARNING: THIS FILE WAS AUTOGENERATED! DO NOT EDIT! -->

![CI](https://github.com/fastai/nbdev/actions/workflows/test.yaml/badge.svg)

## 🛑**Jan 2026 Major Version Update – Breaking Change**🛑

**nbdev3 is here!** As many of you have been requesting, configuration has moved from `settings.ini` to `pyproject.toml`, following modern Python packaging standards ([PEP 621](https://peps.python.org/pep-0621/)). Your project metadata now lives in the standard `[project]` section, while nbdev-specific settings go in `[tool.nbdev]`.

**Migrating from nbdev2:** Run `nbdev-migrate-config` in your project root to automatically convert your `settings.ini` to `pyproject.toml` and update your GitHub Actions workflows to use nbdev3-compatible versions. Your existing notebooks and code don’t need any changes.

`nbdev` is a notebook-driven development platform. Simply write notebooks with lightweight markup and get high-quality documentation, tests, continuous integration, and packaging for free!

`nbdev` makes debugging and refactoring your code much easier than in traditional programming environments since you always have live objects at your fingertips. `nbdev` also promotes software engineering best practices because tests and documentation are first class.

- **Documentation** is automatically generated using [Quarto](https://quarto.org/) and hosted on [GitHub Pages](https://pages.github.com/). Docs support LaTeX, are searchable, and are automatically hyperlinked (including out-of-the-box support for many packages via [`nbdev-index`](https://github.com/fastai/nbdev-index))
- **Publish packages to PyPI and conda** as well as tools to simplify package releases. Python best practices are automatically followed, for example, only exported objects are included in `__all__`
- **Two-way sync between notebooks and plaintext source code** allowing you to use your IDE for code navigation or quick edits. Sync is robust: each exported cell is tagged with its unique notebook cell ID, so `nbdev-update` always updates the correct cell
- **Tests** written as ordinary notebook cells are run in parallel with a single command
- **Continuous integration** out-of-the-box with [GitHub Actions](https://github.com/features/actions) that run your tests and rebuild your docs
- **Git-friendly notebooks** with [Jupyter/Git hooks](https://nbdev.fast.ai/tutorials/git_friendly_jupyter.html) that clean unwanted metadata and render merge conflicts in a human-readable format
- … and much more!

## Install

nbdev works on macOS, Linux, and most Unix-style operating systems. It works on Windows under WSL, but not under cmd or Powershell.

You can install nbdev with pip:

``` sh
pip install nbdev
```

Note that `nbdev` must be installed into the same Python environment that you use for both Jupyter and your project.

## How to use nbdev

The best way to learn how to use nbdev is to complete either the [written walkthrough](https://nbdev.fast.ai/tutorials/tutorial.html) or video walkthrough:

<a href="http://www.youtube.com/watch?v=l7zS8Ld4_iA" target="_blank" title="nbdev walkthrough"><img src="https://github.com/fastai/logos/raw/main/nbdev_walkthrough.png" style="border-radius: 10px" width="560" height="315" /></a>

Alternatively, there’s a [shortened version of the video walkthrough](https://youtu.be/67FdzLSt4aA) with coding sections sped up using the `unsilence` Python library – it’s 27 minutes faster, but a bit harder to follow.

You can also run `nbdev-help` from the terminal to see the full list of available commands:

``` python
!nbdev-help
```

    nb-export                 Export a single nbdev notebook to a python script.
    nbdev-bump-version        Increment version in __init__.py by one
    nbdev-changelog           Create a CHANGELOG.md file from closed and labeled GitHub issues
    nbdev-clean               Clean all notebooks in `fname` to avoid merge conflicts
    nbdev-conda               Create a `meta.yaml` file ready to be built into a package, and optionally build and upload it
    nbdev-contributing        Create CONTRIBUTING.md from contributing_nb (defaults to 'contributing.ipynb' if present). Skips if the file doesn't exist.
    nbdev-create-config       Create a pyproject.toml config file.
    nbdev-docs                Create Quarto docs and README.md
    nbdev-export              Export notebooks in `path` to Python modules
    nbdev-filter              A notebook filter for Quarto
    nbdev-fix                 Create working notebook from conflicted notebook `nbname`
    nbdev-help                Show help for all console scripts
    nbdev-install             Install Quarto and the current library
    nbdev-install-hooks       Install Jupyter and git hooks to automatically clean, trust, and fix merge conflicts in notebooks
    nbdev-install-quarto      Install latest Quarto on macOS or Linux, prints instructions for Windows
    nbdev-merge               Git merge driver for notebooks
    nbdev-migrate             Convert all markdown and notebook files in `path` from v1 to v2
    nbdev-migrate-config      Migrate settings.ini to pyproject.toml
    nbdev-new                 Create an nbdev project.
    nbdev-prepare             Export, test, and clean notebooks, and render README if needed
    nbdev-preview             Preview docs locally
    nbdev-proc-nbs            Process notebooks in `path` for docs rendering
    nbdev-pypi                Create and upload Python package to PyPI
    nbdev-readme              Create README.md from readme_nb (index.ipynb by default)
    nbdev-release-both        Release both conda and PyPI packages
    nbdev-release-gh          Calls `nbdev-changelog`, lets you edit the result, then pushes to git and calls `nbdev-release-git`
    nbdev-release-git         Tag and create a release in GitHub for the current version
    nbdev-requirements        Writes a `requirements.txt` file to `directory` based on pyproject.toml.
    nbdev-sidebar             Create sidebar.yml
    nbdev-test                Test in parallel notebooks matching `path`, passing along `flags`
    nbdev-trust               Trust notebooks matching `fname`.
    nbdev-update              Propagate change in modules matching `fname` to notebooks that created them
    nbdev-update-license      Allows you to update the license of your project.
    watch-export              Use `nb_export` on ipynb files in `nbs` directory on changes using nbdev config if available

## FAQ

### Q: What is the warning “Found a cell containing mix of imports and computations. Please use separate cells”?

A: You should not have cells that are not exported, *and* contain a mix of `import` statements along with other code. For instance, don’t do this in a single cell:

``` python
import some_module
some_module.something()
```

Instead, split this into two cells, one which does `import some_module`, and the other which does `some_module.something()`.

Only top-level statements count: `try: import` blocks and imports inside function definitions are fine.

The reason for this is that when we create your documentation website, we ensure that all of the signatures for functions you document are up to date, by running the imports, exported cells, and [`show_doc`](https://nbdev.fast.ai/api/showdoc.html#show_doc) functions in your notebooks. When you mix imports with other code, that other code will be run too, which can cause errors (or at least slowdowns) when creating your website.

### Q: Why is nbdev asking for root access? How do I install Quarto without root access?

A: When you setup your first project, nbdev will attempt to automatically download and install [Quarto](https://quarto.org/) for you. This is the program that we use to create your documentation website.

Quarto’s standard installation process requires root access, and nbdev will therefore ask for your root password during installation. For most people, this will work fine and everything will be handled automatically – if so, you can skip over the rest of this section, which talks about installing without root access.

If you need to install Quarto without root access on Linux, first `cd` to wherever you want to store it, then [download Quarto](https://quarto.org/docs/get-started/), and type:

``` bash
dpkg -x quarto*.deb .
mv opt/quarto ./
rmdir opt
mkdir -p ~/.local/bin
ln -s "$(pwd)"/quarto/bin/quarto ~/.local/bin
```

To use this non-root version of Quarto, you’ll need `~/.local/bin` in your [`PATH` environment variable](https://linuxize.com/post/how-to-add-directory-to-path-in-linux/). (Alternatively, change the `ln -s` step to place the symlink somewhere else in your path.)

### Q: Someone told me not to use notebooks for “serious” software development!

A: [Watch this video](https://youtu.be/9Q6sLbz37gk). Don’t worry, we still get this too, despite having used `nbdev` for a wide range of “very serious” software projects over the last three years, including [deep learning libraries](https://github.com/fastai/fastai), [API clients](https://github.com/fastai/ghapi), [Python language extensions](https://github.com/fastai/fastcore), [terminal user interfaces](https://github.com/nat/ghtop), and more!

## Contributing

If you want to contribute to `nbdev`, be sure to review the [contributions guidelines](https://github.com/fastai/nbdev/blob/master/CONTRIBUTING.md). This project adheres to fastai’s [code of conduct](https://github.com/fastai/nbdev/blob/master/CODE_OF_CONDUCT.md). By participating, you are expected to uphold this code. In general, we strive to abide by generally accepted best practices in open-source software development.

Make sure you have `nbdev`’s git hooks installed by running `nbdev-install-hooks` in the cloned repository.

## Copyright

Copyright © 2019 onward fast.ai, Inc. Licensed under the Apache License, Version 2.0 (the “License”); you may not use this project’s files except in compliance with the License. A copy of the License is provided in the LICENSE file in this repository.
