├── server-1.x ├── .jupyter │ ├── jupyter_lab_config.json │ ├── jupyter_lab_config.py │ ├── jupyter_notebook_config.json │ ├── jupyter_notebook_config.py │ ├── jupyter_config.json │ ├── jupyter_server_config.json │ ├── jupyter_server_config.py │ ├── jupyter_config.py │ └── README.md ├── {sys_prefix} │ └── etc │ │ └── jupyter │ │ ├── jupyter_lab_config.py │ │ ├── jupyter_lab_config.json │ │ ├── jupyter_notebook_config.py │ │ ├── jupyter_notebook_config.json │ │ ├── jupyter_config.json │ │ ├── jupyter_server_config.json │ │ ├── jupyter_config.py │ │ ├── jupyter_server_config.py │ │ ├── jupyter_server_config.d │ │ ├── notebook.json │ │ ├── jupyterlab.json │ │ ├── my_extension.json │ │ └── README.md │ │ └── README.md └── README.md ├── notebook-5.x ├── .jupyter │ ├── jupyter_config.json │ ├── jupyter_notebook_config.json │ ├── jupyter_notebook_config.py │ ├── jupyter_config.py │ └── README.md ├── {sys_prefix} │ └── etc │ │ └── jupyter │ │ ├── jupyter_notebook_config.json │ │ ├── jupyter_notebook_config.d │ │ ├── jupyterlab.json │ │ ├── my_extension.json │ │ └── README.md │ │ ├── jupyter_config.py │ │ ├── jupyter_notebook_config.py │ │ └── README.md └── README.md └── README.md /server-1.x/.jupyter/jupyter_lab_config.json: -------------------------------------------------------------------------------- 1 | -------------------------------------------------------------------------------- /server-1.x/.jupyter/jupyter_lab_config.py: -------------------------------------------------------------------------------- 1 | -------------------------------------------------------------------------------- /server-1.x/.jupyter/jupyter_notebook_config.json: -------------------------------------------------------------------------------- 1 | -------------------------------------------------------------------------------- /server-1.x/.jupyter/jupyter_notebook_config.py: -------------------------------------------------------------------------------- 1 | -------------------------------------------------------------------------------- /server-1.x/{sys_prefix}/etc/jupyter/jupyter_lab_config.py: -------------------------------------------------------------------------------- 1 | -------------------------------------------------------------------------------- /server-1.x/{sys_prefix}/etc/jupyter/jupyter_lab_config.json: -------------------------------------------------------------------------------- 1 | -------------------------------------------------------------------------------- /server-1.x/{sys_prefix}/etc/jupyter/jupyter_notebook_config.py: -------------------------------------------------------------------------------- 1 | -------------------------------------------------------------------------------- /server-1.x/{sys_prefix}/etc/jupyter/jupyter_notebook_config.json: -------------------------------------------------------------------------------- 1 | -------------------------------------------------------------------------------- /server-1.x/.jupyter/jupyter_config.json: -------------------------------------------------------------------------------- 1 | { 2 | "ServerApp": { 3 | "open_browser": true 4 | } 5 | } -------------------------------------------------------------------------------- /notebook-5.x/.jupyter/jupyter_config.json: -------------------------------------------------------------------------------- 1 | { 2 | "NotebookApp": { 3 | "open_browser": true 4 | } 5 | } -------------------------------------------------------------------------------- /server-1.x/.jupyter/jupyter_server_config.json: -------------------------------------------------------------------------------- 1 | { 2 | "ServerApp": { 3 | "open_browser": true 4 | } 5 | } -------------------------------------------------------------------------------- /notebook-5.x/.jupyter/jupyter_notebook_config.json: -------------------------------------------------------------------------------- 1 | { 2 | "NotebookApp": { 3 | "open_browser": false 4 | } 5 | } -------------------------------------------------------------------------------- /server-1.x/{sys_prefix}/etc/jupyter/jupyter_config.json: -------------------------------------------------------------------------------- 1 | { 2 | "ServerApp": { 3 | "open_browser": true 4 | } 5 | } -------------------------------------------------------------------------------- /server-1.x/{sys_prefix}/etc/jupyter/jupyter_server_config.json: -------------------------------------------------------------------------------- 1 | { 2 | "ServerApp": { 3 | "open_browser": true 4 | } 5 | } -------------------------------------------------------------------------------- /notebook-5.x/{sys_prefix}/etc/jupyter/jupyter_notebook_config.json: -------------------------------------------------------------------------------- 1 | { 2 | "NotebookApp": { 3 | "open_browser": false 4 | } 5 | } -------------------------------------------------------------------------------- /server-1.x/{sys_prefix}/etc/jupyter/jupyter_config.py: -------------------------------------------------------------------------------- 1 | # Set configurations as nested objects under 'c'. 2 | c.ServerApp.open_browser = True 3 | -------------------------------------------------------------------------------- /server-1.x/{sys_prefix}/etc/jupyter/jupyter_server_config.py: -------------------------------------------------------------------------------- 1 | # Set configurations as nested objects under 'c'. 2 | c.ServerApp.open_browser = True 3 | -------------------------------------------------------------------------------- /server-1.x/{sys_prefix}/etc/jupyter/jupyter_server_config.d/notebook.json: -------------------------------------------------------------------------------- 1 | { 2 | "ServerApp": { 3 | "jpserver_extensions": { 4 | "notebook": true 5 | } 6 | } 7 | } -------------------------------------------------------------------------------- /server-1.x/{sys_prefix}/etc/jupyter/jupyter_server_config.d/jupyterlab.json: -------------------------------------------------------------------------------- 1 | { 2 | "ServerApp": { 3 | "jpserver_extensions": { 4 | "jupyterlab": true 5 | } 6 | } 7 | } -------------------------------------------------------------------------------- /notebook-5.x/{sys_prefix}/etc/jupyter/jupyter_notebook_config.d/jupyterlab.json: -------------------------------------------------------------------------------- 1 | { 2 | "NotebookApp": { 3 | "nbserver_extensions": { 4 | "jupyterlab": true 5 | } 6 | } 7 | } -------------------------------------------------------------------------------- /server-1.x/{sys_prefix}/etc/jupyter/jupyter_server_config.d/my_extension.json: -------------------------------------------------------------------------------- 1 | { 2 | "ServerApp": { 3 | "jpserver_extensions": { 4 | "my_extension": true 5 | } 6 | } 7 | } -------------------------------------------------------------------------------- /notebook-5.x/{sys_prefix}/etc/jupyter/jupyter_notebook_config.d/my_extension.json: -------------------------------------------------------------------------------- 1 | { 2 | "NotebookApp": { 3 | "nbserver_extensions": { 4 | "my_extension": true 5 | } 6 | } 7 | } -------------------------------------------------------------------------------- /server-1.x/.jupyter/jupyter_server_config.py: -------------------------------------------------------------------------------- 1 | # Set configurations as nested objects under 'c'. 2 | # Whether to open the browser window automatically or not. 3 | # This overrides jupyter_config.py|json 4 | c.ServerApp.open_browser = False 5 | -------------------------------------------------------------------------------- /notebook-5.x/.jupyter/jupyter_notebook_config.py: -------------------------------------------------------------------------------- 1 | # Set configurations as nested objects under 'c'. 2 | # Whether to open the browser window automatically or not. 3 | # NOTE: This overrides `jupyter_config.py|json` setting. 4 | c.NotebookApp.open_browser = False 5 | -------------------------------------------------------------------------------- /notebook-5.x/.jupyter/jupyter_config.py: -------------------------------------------------------------------------------- 1 | # Set configurations as nested objects under 'c'. 2 | # Whether to open the browser window automatically or not. 3 | c.NotebookApp.open_browser = True 4 | 5 | # Change the port that the notebook server will listen on. 6 | c.NotebookApp.port = 9999 7 | 8 | # Change the culling time of the KernelManager 9 | c.KernelManager.cull_idle_timeout = 1000 -------------------------------------------------------------------------------- /server-1.x/.jupyter/jupyter_config.py: -------------------------------------------------------------------------------- 1 | # Set configurations as nested objects under 'c'. 2 | # Whether to open the browser window automatically or not. 3 | c.ServerApp.open_browser = True 4 | 5 | # Change the port that the server will listen on. 6 | c.ServerApp.port = 9999 7 | 8 | # Change the culling time of the KernelManager 9 | c.KernelManager.cull_idle_timeout = 1000 10 | -------------------------------------------------------------------------------- /notebook-5.x/{sys_prefix}/etc/jupyter/jupyter_config.py: -------------------------------------------------------------------------------- 1 | # Set configurations as nested objects under 'c'. 2 | # This overrides configurations in `~/.jupyter` 3 | c.NotebookApp.open_browser = True 4 | 5 | # Change the port that the notebook server will listen on. 6 | c.NotebookApp.port = 9999 7 | 8 | # Change the culling time of the KernelManager 9 | c.KernelManager.cull_idle_timeout = 1000 10 | -------------------------------------------------------------------------------- /notebook-5.x/{sys_prefix}/etc/jupyter/jupyter_notebook_config.py: -------------------------------------------------------------------------------- 1 | # Set configurations as nested objects under 'c'. 2 | # This overrides configurations in `~/.jupyter` 3 | c.NotebookApp.open_browser = True 4 | # Set configurations as nested objects under 'c'. 5 | # Whether to open the browser window automatically or not. 6 | # NOTE: This overrides `jupyter_config.py` setting. 7 | c.NotebookApp.open_browser = False 8 | -------------------------------------------------------------------------------- /server-1.x/{sys_prefix}/etc/jupyter/jupyter_server_config.d/README.md: -------------------------------------------------------------------------------- 1 | # Server Extension Listing and Enabling 2 | 3 | This directory is **only** for listing and enabling server extensions. Each file is for a separate server extension and contains the JSON code like: 4 | ```json 5 | { 6 | "ServerApp": { 7 | "jpserver_extensions": { 8 | "jupyterlab": true 9 | } 10 | } 11 | } 12 | ``` 13 | This code is imforms the `ServerApp` which extensions should be loaded and enabled. -------------------------------------------------------------------------------- /notebook-5.x/{sys_prefix}/etc/jupyter/jupyter_notebook_config.d/README.md: -------------------------------------------------------------------------------- 1 | # Server Extension Listing and Enabling 2 | 3 | This directory is **only** for listing and enabling server extensions. Each file is for a separate server extension and contains the JSON code like: 4 | ```json 5 | { 6 | "NotebookApp": { 7 | "nbserver_extensions": { 8 | "jupyterlab": true 9 | } 10 | } 11 | } 12 | ``` 13 | This code is imforms the `NotebookApp` which extensions should be loaded and enabled. -------------------------------------------------------------------------------- /notebook-5.x/.jupyter/README.md: -------------------------------------------------------------------------------- 1 | # Global configuration 2 | 3 | Remember, `~/.jupyter` lives in your home directory and should be treated as "global" configurations. These config settings persist across Python environments. 4 | 5 | Summary: 6 | * `jupyter_config.py|json` should be treated as a general configuration file. You can put all your application's configuration in this single file. However, other configuration files will override these settings. 7 | * `jupyter_notebook_config.py|json` list configurations applied to the `NotebookApp` and its various pieces. -------------------------------------------------------------------------------- /server-1.x/README.md: -------------------------------------------------------------------------------- 1 | # Configuration for Jupyter Notebook (5.x) 2 | 3 | This folder demonstrates Jupyter's configuration system if you're using Jupyter Notebook 5.x. 4 | 5 | Jupyter searches for configuration files in a few locations: 6 | 7 | * Configuration in the current location overrides all other configurations 8 | * `jupyter --paths` lists the paths where Jupyter looks for configs in order of precedence. Configs in the locations at the top of the list override config at the bottom of the list. 9 | * Configuration in `~/.jupyter` should be treated as "global" configuration. These config settings persist across Python environments. 10 | * configuration in `{sys-prefix}/etc/jupyter` should be treated as "local" configuration. These settings are specific to the current Python environment. -------------------------------------------------------------------------------- /notebook-5.x/README.md: -------------------------------------------------------------------------------- 1 | # Configuration for Jupyter Notebook (5.x) 2 | 3 | This folder demonstrates Jupyter's configuration system if you're using Jupyter Notebook 5.x. 4 | 5 | Jupyter searches for configuration files in a few locations: 6 | 7 | * Configuration in the current location overrides all other configurations 8 | * `jupyter --paths` lists the paths where Jupyter looks for configs in order of precedence. Configs in the locations at the top of the list override config at the bottom of the list. 9 | * Configuration in `~/.jupyter` should be treated as "global" configuration. These config settings persist across Python environments. 10 | * configuration in `{sys-prefix}/etc/jupyter` should be treated as "local" configuration. These settings are specific to the current Python environment. -------------------------------------------------------------------------------- /notebook-5.x/{sys_prefix}/etc/jupyter/README.md: -------------------------------------------------------------------------------- 1 | # Local configuration 2 | 3 | Remember, `{sys-prefix}/etc/jupyter` should be treated as the home for "local" configurations. These config settings are specific to your current Jupyter/Python environment. 4 | 5 | Summary: 6 | * `jupyter_config.py|json` should be treated as a general configuration file. You can put all your application's configuration in this single file. However, other configuration files will override these settings. 7 | * `jupyter_notebook_config.py|json` list configurations applied to the `NotebookApp` and its various pieces. 8 | * `jupyter_notebook_config.d/` is a directory for listing and enabling server extensions **only**. User-defined configuration should **not** go in this directory. In summary, you shouldn't need to touch this directory. 9 | -------------------------------------------------------------------------------- /server-1.x/.jupyter/README.md: -------------------------------------------------------------------------------- 1 | # Global configuration 2 | 3 | Remember, `~/.jupyter` lives in your home directory and should be treated as "global" configurations. These config settings persist across Python environments. 4 | 5 | Summary: 6 | * `jupyter_config.py|json` should be treated as a general configuration file. You can put all your application's configuration in this single file. However, other configuration files will override these settings. 7 | * `jupyter_server_config.py|json` list configurations applied to the `ServerApp` and its various managers, services, etc. 8 | * `jupyter_notebook_config.py|json` list configurations applied to the `NotebookApp`. 9 | * `jupyter_lab_config.py|json` list configurations applied to the `LabApp`. 10 | * `jupyter_my_extension_config.py|json` list configurations applied to the `MyExtensionsApp`. -------------------------------------------------------------------------------- /server-1.x/{sys_prefix}/etc/jupyter/README.md: -------------------------------------------------------------------------------- 1 | # Local configuration 2 | 3 | Remember, `{sys-prefix}/etc/jupyter` should be treated as the home for "local" configurations. These config settings are specific to your current Jupyter/Python environment. 4 | 5 | Summary: 6 | * `jupyter_config.py|json` should be treated as a general configuration file. You can put all your application's configuration in this single file. However, other configuration files will override these settings. 7 | * `jupyter_server_config.py|json` list configurations applied to the `ServerApp` and its various managers, services, etc. 8 | * `jupyter_notebook_config.py|json` list configurations applied to the `NotebookApp`. 9 | * `jupyter_lab_config.py|json` list configurations applied to the `LabApp`. 10 | * `jupyter_my_extension_config.py|json` list configurations applied to the `MyExtensionApp`. -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # How to navigate Jupyter's configuration system 2 | 3 | *A walk through Jupyter's (server) configuration system* 4 | 5 | Feel free to explore this repository to get familiar with Jupyter's config layout. The `notebook-5.x` directory shows an example of the current configuration design. The `server-1.x` shows an example of the (possible) future configuration design under the Jupyter Server Enhancement Proposal. Each directory includes a README explaining the content in that directory. 6 | 7 | **Table of Contents** 8 | 9 | * [Who is this overview for?](#who-is-this-overview-for) 10 | * [General Overview](#configuration-at-a-glance) 11 | * [Which configuration wins?](#which-configuration-wins) 12 | * [Jupyter Notebook 5.x vs. Server 1.x](#jupyter-notebook-5x-vs-server-1x) 13 | * [Contributing](#contributing) 14 | 15 | ## Who is this overview for? 16 | 17 | This overview targets more experienced Jupyter users and contributors. If you're new to Jupyter, you probably haven't (knowingly) touched Jupyter's configuration system. If you *have* tried configuring your Jupyter experience, this is a good place to start. 18 | 19 | ## General Overview 20 | 21 | This repository demostrates the directory structure of Jupyter's configuration system. Explore the contents of this repository to see configuration examples and learn more information about each specific file. 22 | 23 | Summary: 24 | * `.jupyter/` will be found in your home directory. 25 | * `{sys-prefix}/` will be found where platform independent Python files are installed. Typically this looks like `/user/local/`. If you're using conda, this usually looks like: `~/miniconda3/etc/jupyter`. If you're inside a conda environment, it might look like: `~/miniconda3/envs/myenv/etc/jupyter`. 26 | * Treat configuration files in `~/.jupyter/` as *global configurations*. They will be enabled in every jupyter environment (i.e. all virtual environments will inherit these configs) **and** override their configurations. 27 | * Treat configurations under `{sys-prefix}` as *local configurations*. They only work inside your current environment. 28 | * `jupyter_config.py|json` is useful for storing all configuration (NotebookApp, Extensions, etc.) in a single file. 29 | * `jupyter_*_.py|json` is used for application specific configuration. 30 | 31 | List of Rules (in order): 32 | 33 | 1. Configuration files in the current directory override all other configuration files. 34 | 2. Jupyter then looks for configuration files in paths listed by `jupyter --paths` under the `config` section. These paths are ranked in order of authority. Configurations found in the top paths override configuration in the lower paths. 35 | 3. Configurations in `jupyter_*_config.py|json` files override configurations in `jupyter_config.py|json` files. 36 | 4. JSON configuration files override Python configuration files. 37 | 5. Configuration files in `jupyter_notebook_config.d` folders are for server extensions **only**. They must be in JSON. 38 | 39 | ## Which configuration wins? 40 | 41 | This section lists a few "who wins?" scenarios. The configuration file that "wins" in each row is **bolded**. 42 | 43 | | Who wins? | Why?| 44 | |----------|----------| 45 | | **
{sys-prefix}/etc/jupyter/jupyter_notebook_config.py
** 
{sys-prefix}/etc/jupyter/jupyter_notebook_config.d/my_extension.json
| The `my_extension.json` file can only touch the `nbserver_extension` attribute. If this attribute is set in both files, the JSON file overrides settings in the Python file (according to Rule 4) *without warning*. | 46 | | **
{sys-prefix}/etc/jupyter/jupyter_notebook_config.json
** 
{sys-prefix}/etc/jupyter/jupyter_notebook_config.d/my_extension.json
| The `my_extension.json` file can only touch the `nbserver_extension` attribute. If this attribute is set in both files, the `jupyter_notebook_config.json` file overrides the `my_extension.json` file *without warning*. | 47 | | **
{sys-prefix}/etc/jupyter/jupyter_notebook_config.d/extension1.json
** 
{sys-prefix}/etc/jupyter/jupyter_notebook_config.d/extension2.json
| Config files in `jupyter_notebook_config.d` are read in order (sorted by your filesystem). Settings in earlier files will be overridden by those same settings in later files *without warning*. | 48 | | 
{sys-prefix}/etc/jupyter/jupyter_notebook_config.py
**
{sys-prefix}/etc/jupyter/jupyter_notebook_config.json
** | Both files are loaded, but the configuration settings in the JSON file override the settings in the Python (according to Rule 4). If you have conflicting settings, *a warning* appears in the logs. | 49 | | 
{sys-prefix}/etc/jupyter/jupyter_config.py
**
{sys-prefix}/etc/jupyter/jupyter_notebook_config.py
** | `jupyter_notebook_config.py` overrides settings in `jupyter_config.py`, following Rule 3. | 50 | | 
{sys-prefix}/etc/jupyter/jupyter_config.json
**
{sys-prefix}/etc/jupyter/jupyter_notebook_config.py
** | `jupyter_notebook_config.py` overrides settings in `jupyter_config.json`, following Rule 3.| 51 | | **
~/.jupyter/jupyter_notebook_config.py
** 
{sys-prefix}/etc/jupyter/jupyter_notebook_config.py
| Following Rule 1, configuration under `~/.jupyter` overrides `{sys-prefix}`. | 52 | 53 | ## Jupyter Notebook 5.x vs. Server 1.x 54 | 55 | This is an overview of how the configuration system changes under the Jupyter Server Enhancement Proposal. This JEP proposes to break out the Jupyter Server from the classic Notebook frontend; currently, they are deeply coupled. The notebook application would become a jupyter server extension, similar to how jupyter lab is currently a notebook server extension. 56 | 57 | List of differences 58 | * Move server-specific configuration from `jupyter_notebook_config.py|json` into `jupyter_server_config.py|json`. 59 | * Server extensions configurations move from `jupyter_notebok_config.d` to `jupyter_server_config.d`. 60 | * The tornado server and web application move to `jupyter_server`. They become `ServerApplication` and `ServerWebApp` 61 | * The `NotebookApp` becomes a server extension. It would only load notebook specific configuration/traitlets, from `jupyter_notebook_config.py|json`. 62 | * Server extensions are found using the `jpserver_extensions` trait instead of the `nbserver_extensions` trait in the `ServerApp`. 63 | * Extension configuration files in `jupyter_server_config.d` must be enabled using the `jpserver_extensions` trait. They are enabled by config files in `jupyter_server_config.d`. 64 | * Extensions can create their own configuration files in `{sys-prefix}/etc/jupyter/` or `~/.jupyter`. 65 | , i.e. `jupyter__config.py|json`. 66 | 67 | To avoid breaking backwards compatibility, we could simply copy user's configurations into new locations. 68 | * **Copy** `jupyter_notebook_config.py|json` to `jupyter_server_config.py|json` 69 | * **Copy** `jupyter_notebook_config.d/` to `jupyter_server_config.d`. 70 | * `NotebookApp` becomes `ServerApp` in all copied files. 71 | * Leftover server traits in `jupyter_notebook_config.py|json` get ignored when the notebook extension is started. 72 | 73 | ## Contributing 74 | 75 | If you see any mistakes, please let me know (open an issue)! I'd like to get this right and prevent extra confusion. If there is something missing or unclear, feel free to submit a pull request. 76 | 77 | --------------------------------------------------------------------------------