{"id":5788,"library":"nbmake","title":"nbmake","description":"nbmake is a pytest plugin designed for testing Jupyter notebooks. It executes notebooks programmatically, allowing for continuous integration and automated quality checks on documentation and research materials. Currently at version 1.5.5, the library maintains an active development cadence, frequently releasing updates to support new Python and Pytest versions and address user feedback.","status":"active","version":"1.5.5","language":"en","source_language":"en","source_url":"https://github.com/treebeardtech/nbmake","tags":["pytest","notebooks","testing","jupyter","ci"],"install":[{"cmd":"pip install nbmake pytest","lang":"bash","label":"Install nbmake and Pytest"}],"dependencies":[{"reason":"nbmake is a plugin for the pytest testing framework.","package":"pytest","optional":false},{"reason":"Used internally by nbmake for notebook execution.","package":"nbclient","optional":false},{"reason":"Required for running notebooks with specific, non-default Jupyter kernels, especially in CI environments.","package":"ipykernel","optional":true}],"imports":[{"note":"Users typically interact with nbmake through the 'pytest' command with the '--nbmake' flag, rather than importing symbols into Python test files.","symbol":"nbmake","correct":"nbmake is primarily used as a pytest plugin via the command line; direct Python imports of 'nbmake' are generally not required for basic usage."}],"quickstart":{"code":"import os\n\n# Create a dummy notebook for testing\nnotebook_content = \"\"\"\n{\n \"cells\": [\n  {\n   \"cell_type\": \"code\",\n   \"execution_count\": null,\n   \"metadata\": {},\n   \"outputs\": [],\n   \"source\": [\n    \"x = 1\\n\",\n    \"y = 2\\n\",\n    \"assert x + y == 3\"\n   ]\n  },\n  {\n   \"cell_type\": \"code\",\n   \"execution_count\": null,\n   \"metadata\": {},\n   \"outputs\": [],\n   \"source\": [\n    \"print('Notebook executed successfully')\"\n   ]\n  }\n ],\n \"metadata\": {\n  \"kernelspec\": {\n   \"display_name\": \"Python 3\",\n   \"language\": \"python\",\n   \"name\": \"python3\"\n  },\n  \"language_info\": {\n   \"codemirror_mode\": {\n    \"name\": \"ipython\",\n    \"version\": 3\n   },\n   \"file_extension\": \".py\",\n   \"mimetype\": \"text/x-python\",\n   \"name\": \"python\",\n   \"nbconvert_exporter\": \"python\",\n   \"pygments_lexer\": \"ipython3\",\n   \"version\": \"3.9.7\"\n  }\n },\n \"nbformat\": 4,\n \"nbformat_minor\": 5\n}\n\"\"\"\n\nwith open(\"test_notebook.ipynb\", \"w\") as f:\n    f.write(notebook_content)\n\n# To run this, save it as a .py file and execute from your terminal:\n# python -c \"$(cat your_script.py)\" # (or simply run the file)\n# Then, in the same directory:\n# pytest --nbmake test_notebook.ipynb\n\nprint(\"Created test_notebook.ipynb. Run 'pytest --nbmake test_notebook.ipynb' in your terminal.\")","lang":"python","description":"To quickly test a Jupyter notebook, install `nbmake` and `pytest`, then invoke pytest with the `--nbmake` flag on your notebook file(s). nbmake will execute the notebook from top to bottom, failing if any cell raises an unhandled exception or an assertion fails. Wildcards can be used to test multiple notebooks."},"warnings":[{"fix":"Upgrade to Python 3.8+ (preferably 3.9+) or pin nbmake to a version <1.5.0.","message":"nbmake v1.5.0 dropped support for Python 3.7. Users on older Python versions will need to upgrade their Python environment or use an older nbmake version.","severity":"breaking","affected_versions":">=1.5.0"},{"fix":"Upgrade to Python 3.9 or newer. Python 3.12 is officially supported by nbmake 1.5.5.","message":"nbmake v1.5.5 dropped support for Python 3.8, which reached end-of-life in October 2024. Users running Python 3.8 should upgrade their Python environment.","severity":"breaking","affected_versions":">=1.5.5"},{"fix":"Ensure all necessary Python packages are installed in the test environment (e.g., via `pip install -e .` for local packages or `pip install -r requirements.txt`). For kernel issues, install the required Jupyter kernel (`python -m ipykernel install --user --name mycustomkernel`) or use `--nbmake-kernel=mycustomkernel` to override. Use `--nbmake-find-import-errors` to specifically diagnose import issues.","message":"Notebooks can fail during testing due to missing Python package dependencies or an incorrect Jupyter kernel in the execution environment, particularly in CI setups. This results in `ModuleNotFoundError` or 'No such kernel' errors.","severity":"gotcha","affected_versions":"All"},{"fix":"Increase the per-cell timeout using `pytest --nbmake --nbmake-timeout=<seconds>` (e.g., `--nbmake-timeout=3000` for 50 minutes). Alternatively, mock out variables or skip complex cells using notebook metadata.","message":"Long-running cells in notebooks can cause tests to time out. Default timeouts might be too strict for some computational tasks.","severity":"gotcha","affected_versions":"All"},{"fix":"For a cell expected to raise an exception, add `\"tags\": [\"raises-exception\"]` to its metadata. For an entire notebook, add `\"execution\": {\"allow_errors\": true}` to its top-level metadata. To skip a cell entirely, use `\"tags\": [\"skip-execution\"]`.","message":"Some notebook cells or entire notebooks are designed to raise exceptions. By default, `nbmake` will treat these as failures.","severity":"gotcha","affected_versions":"All"},{"fix":"Install your project in editable mode (`pip install -e .`) so Python can find modules. Alternatively, ensure the notebook's directory is on the Python path during testing, or modify `sys.path` within the notebook itself, though this is generally less robust.","message":"Relative imports within notebooks (e.g., `from .. import my_module`) often fail when run by `pytest --nbmake` if the project structure isn't correctly handled by pytest or the package isn't installed in 'editable' mode.","severity":"gotcha","affected_versions":"All"}],"env_vars":null,"last_verified":"2026-04-14T00:00:00.000Z","next_check":"2026-07-13T00:00:00.000Z"}