A python cli program to open jupyter notebooks from a central server.

I typically run a single jupyter notebook server, and want to launch notebooks from several locations in the file system. This can be done from the tree view of jupyter notebook, but I want to quickly open notebooks from the command line using the central server. open-notebook will open notebooks from anywhere relative to a central server.

• Can specify options like host, and port from the command line
• Defaults can be configured using the configuration file(s) .open-notebook.toml.
• Open both jupyter notebooks, and directories (in tree view).

This package is actively used by the author. Please feel free to create a pull request for wanted features and suggestions!

To install, use one of the following:

pip/pipx/uv pip/uv tool install open-notebook
# or
conda/condax install -c conda-forge open-notebook

We recommend using uv tool install so that the application is available at all times.

The main command-line program is open-notebook with the following options:

$ open-notebook --help
usage: open-notebook [-h] [--host HOST] [-p PORT] [-r ROOT] [--dir-prefix DIR_PREFIX]
                     [--file-prefix FILE_PREFIX] [--reset] [-c CONFIG] [--create-config]
                     [--overwrite] [--version] [-v] [--dry]
                     [paths ...]

Program to open jupyter notebooks from central notebook server.

positional arguments:
  paths                 file or paths to open

options:
  -h, --help            show this help message and exit
  --host HOST           Host name (default='localhost')
  -p, --port PORT       Port (default='8888')
  -r, --root ROOT       Directory servers was started in. Defaults to current working
                        directory.
  --dir-prefix DIR_PREFIX
                        Directory prefix (default='tree')
  --file-prefix FILE_PREFIX
                        File prefix (default='notebooks')
  --reset
  -c, --config CONFIG   Config style to use. This is the name of a header in one of the
                        config files.
  --create-config       If passed, create .open-notebook.ini
  --overwrite           Pass to overwrite `~/.open-notebook.toml` if it exists with
                        `--create-config`
  --version             Print out program version
  -v, --verbose         Set verbosity level. Can pass multiple times.
  --dry                 Dry run.

You can set options with the configuration files ".open-notebook.toml". Configuration
files are found in the current directory, git root (if in a git tracked tree), and the
home directory. Note that all these files are considered, in order. That is, you could
override a single value in the current directory, and the rest would be inherited from,
in order, git root and then the home directory.

Equivalently, you can use the short name nopen, or use python -m open_notebook.

To open directory tree view:

open-notebook .

To open a jupyter notebook (here using the short name nopen):

nopen path/to/notebook.ipynb

To specify where the central server is running, use the -r/--root option. For example, if the server is started in the directory "~/test", then you'd pass --root ~/test. For example:

# start server
cd ~/test
jupyter notebook


# cd to some other directory under where notebook was started
cd ~/test/a/different/directory
open-notebook -r ~/test example.ipynb

If you always start a notebook in the same place, you can configure open-notebook as follows:

# ~/.open-notebook.toml
root = "~/test"
port = "8888"

Options name in the configuration file .open-notebook.toml are the same as the command-line options above (replacing dashes with underscores, so, e.g., instead of --dir-prefix value, you'd sed dir_prefix = "value" in the configuration file).

If you use more than one server, you can have multiple notebook configurations. For example, you can specify that the configuration alt uses port 8889 and is run in the home directory using:

# ~/.open-notebook.toml
root = "~/test"
port = "8888"

[alt]
root = "~/"
port = "8889"

The default behavior is the same as above. To use the alt config, then use:

# will use root="~/" and port="8889".  Other options inherited.
open-notebook -c alt ...

open-notebook searches for configuration files .open-notebook.toml in the current directory, the root of a git repo (if you're currently in a git repo), and finally in the home directory. Options are read, in order, from command-line options, current directory config, git root config, and home directory config file. This means that you can specify common configurations at the home level, and then override single options at higher levels. For example, if we have:

# ~/.open-notebook.toml
root = "~/"
host = "8889"

# ~/a/b/.open-notebook.toml
host = "9999"

cd a/b
# this will open notebook with root="~/" and host="9999"
open-notebook example.ipynb

See the documentation for further details.

See changelog.

This is free software. See LICENSE.

The author can be reached at wpk@nist.gov.

This package was created using Cookiecutter with the usnistgov/cookiecutter-nist-python template.