opennb 📓

📓 Open Jupyter notebooks from GitHub repositories or URLs directly in Jupyter. Very useful in conjunction with uvx.

[!TIP] Try uvx --with "pipefunc[docs]" opennb pipefunc/pipefunc/example.ipynb to open a notebook from the pipefunc repository and ensure its dependencies are installed.

Features

• 📦 Open notebooks directly from GitHub repositories
• 🔄 Automatic default branch detection
• 🌳 Support for specific branches
• 🔗 Direct URL support
• 🚀 Pass-through of Jupyter notebook arguments
• 📥 Integration with uvx for dependency management
• 👽 Also works with Jupytext .md or .py notebooks

Usage

Open a notebook from a GitHub repository:

opennb owner/repo/path/to/notebook.ipynb

This defaults to the default branch of the repository.

Or specify a specific branch:

opennb owner/repo@branch#path/to/notebook.ipynb

Open directly from a URL:

opennb https://example.com/notebook.ipynb

[!IMPORTANT] opennb is especially useful when used with uvx.

Use with uvx to install dependencies and open a notebook in one go:

uvx --with dependency opennb owner/repo/path/to/notebook.ipynb

For example, to open a notebook from the pipefunc repository and ensure its dependencies are installed:

uvx --with "pipefunc[docs]" opennb pipefunc/pipefunc/example.ipynb

Arguments

All arguments after the notebook specification are passed directly to jupyter notebook:

opennb owner/repo/notebook.ipynb --port 8888 --no-browser

Examples

Open a notebook from the main branch:

opennb owner/repo/notebook.ipynb

Open from a specific branch:

opennb jupyter/notebook@main#docs/source/examples/Notebook/Notebook%20Basics.ipynb

Open with custom Jupyter settings:

opennb owner/repo/notebook.ipynb --NotebookApp.token='my-token'

Installation

Install using pip:

pip install opennb

Or using uv:

uv pip install opennb

License

MIT License

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.