## 1. Project Overview & Quickstart (jupyter/notebook) ## File: README.md # Jupyter Notebook [](https://jupyter-notebook.readthedocs.io/en/latest/?badge=latest) [](https://mybinder.org/v2/gh/jupyter/notebook/main?urlpath=tree) The Jupyter notebook is a web-based notebook environment for interactive computing. ## Maintained versions We maintain the **two most recently released major versions of Jupyter Notebook**, Classic Notebook v6 and Notebook v7. Notebook v5 is no longer maintained. All Notebook v5 users are strongly advised to upgrade to Classic Notebook v6 as soon as possible. Upgrading to Notebook v7 may require more work, if you use custom extensions, as extensions written for Notebook v5 or Classic Notebook v6 are not compatible with Notebook v7. ### Notebook v7 The newest major version of Notebook is based on: - JupyterLab components for the frontend - Jupyter Server for the Python server This represents a significant change to the `jupyter/notebook` code base. To learn more about Notebook v7: https://jupyter.org/enhancement-proposals/notebook-v7/ ### Classic Notebook v6 Maintenance and security-related issues [only](https://github.com/jupyter/notebook-team-compass/issues/5#issuecomment-1085254000) are now being addressed in the [`6.5.x`](https://github.com/jupyter/notebook/tree/6.5.x) branch. It depends on [`nbclassic`](https://github.com/jupyter/nbclassic) for the HTML/JavaScript/CSS assets. New features and continuous improvement is now focused on Notebook v7 (see section above). If you have an open pull request with a new feature or if you were planning to open one, we encourage switching over to the Jupyter Server and JupyterLab architecture, and distribute it as a server extension and / or JupyterLab prebuilt extension. That way your new feature will also be compatible with the new Notebook v7. ## Jupyter notebook, the language-agnostic evolution of IPython notebook Jupyter notebook is a language-agnostic HTML notebook application for Project Jupyter. In 2015, Jupyter notebook was released as a part of The Big Split™ of the IPython codebase. IPython 3 was the last major monolithic release containing both language-agnostic code, such as the _IPython notebook_, and language specific code, such as the _IPython kernel for Python_. As computing spans across many languages, Project Jupyter will continue to develop the language-agnostic **Jupyter notebook** in this repo and with the help of the community develop language specific kernels which are found in their own discrete repos. - [The Big Split™ announcement](https://blog.jupyter.org/the-big-split-9d7b88a031a7) - [Jupyter Ascending blog post](https://blog.jupyter.org/jupyter-ascending-1bf5b362d97e) ## Installation You can find the installation documentation for the [Jupyter platform, on ReadTheDocs](https://jupyter.readthedocs.io/en/latest/install.html). The documentation for advanced usage of Jupyter notebook can be found [here](https://jupyter-notebook.readthedocs.io/en/latest/). For a local installation, make sure you have [pip installed](https://pip.readthedocs.io/en/stable/installing/) and run: ```bash pip install notebook ``` ## Usage - Running Jupyter notebook ### Running in a local installation Launch with: ```bash jupyter notebook ``` ### Running in a remote installation You need some configuration before starting Jupyter notebook remotely. See [Running a notebook server](https://jupyter-server.readthedocs.io/en/latest/operators/public-server.html). ## Development Installation See [`CONTRIBUTING.md`](CONTRIBUTING.md) for how to set up a local development installation. ## Contributing If you are interested in contributing to the project, see [`CONTRIBUTING.md`](CONTRIBUTING.md). ## Community Guidelines and Code of Conduct This repository is a Jupyter project and follows the Jupyter [Community Guides and Code of Conduct](https://jupyter.readthedocs.io/en/latest/community/content-community.html). ## Resources - [Project Jupyter website](https://jupyter.org) - [Online Demo at jupyter.org/try](https://jupyter.org/try) - [Documentation for Jupyter notebook](https://jupyter-notebook.readthedocs.io/en/latest/) - [Korean Version of Installation](https://github.com/ChungJooHo/Jupyter_Kor_doc/) - [Documentation for Project Jupyter](https://jupyter.readthedocs.io/en/latest/index.html) - [Issues](https://github.com/jupyter/notebook/issues) - [Technical support - Jupyter Google Group](https://discourse.jupyter.org/) ## About the Jupyter Development Team The Jupyter Development Team is the set of all contributors to the Jupyter project. This includes all of the Jupyter subprojects. The core team that coordinates development on GitHub can be found here: https://github.com/jupyter/. ## Our Copyright Policy Jupyter uses a shared copyright model. Each contributor maintains copyright over their contributions to Jupyter. But, it is important to note that these contributions are typically only changes to the repositories. Thus, the Jupyter source code, in its entirety is not the copyright of any single person or institution. Instead, it is the collective copyright of the entire Jupyter Development Team. If individual contributors want to maintain a record of what changes/contributions they have specific copyright on, they should indicate their copyright in the commit message of the change, when they commit the change to one of the Jupyter repositories. With this in mind, the following banner should be used in any source code file to indicate the copyright and license terms: ``` # Copyright (c) Jupyter Development Team. # Distributed under the terms of the Modified BSD License. ``` --- ## File: docs/source/configuring/config_overview.md (configuration-overview)= # Configuration Overview Beyond the default configuration settings, you can configure a rich array of options to suit your workflow. Here are areas that are commonly configured when using Jupyter Notebook: > - {ref}`Jupyter's common configuration system ` > - {ref}`Jupyter Server ` > - {ref}`Notebook extensions ` Let's look at highlights of each area. (configure-common)= ## Jupyter's Common Configuration system Jupyter applications, from the Notebook to JupyterHub to nbgrader, share a common configuration system. The process for creating a configuration file and editing settings is similar for all the Jupyter applications. > - [Jupyter’s Common Configuration Approach](https://jupyter.readthedocs.io/en/latest/use/config.html) > - [Common Directories and File Locations](https://jupyter.readthedocs.io/en/latest/use/jupyter-directories.html) > - [Language kernels](https://jupyter.readthedocs.io/en/latest/projects/kernels.html) > - [traitlets](https://traitlets.readthedocs.io/en/latest/config.html#module-traitlets.config) > provide a low-level architecture for configuration. ### Disabling Custom CSS Custom CSS is loaded by default as was done with Jupyter Notebook 6. In the jupyter configuration directory, the `/.jupyter/custom/custom.css` file will be loaded unless the application is initialized with the `custom_css` flag with the argument set to `False` as in `--JupyterNotebookApp.custom_css=False`. (configure-jupyter-server)= ## Jupyter server The Jupyter Server runs the language kernel and communicates with the front-end Notebook client (i.e. the familiar notebook interface). > - Configuring the Jupyter Server > > > To create a `jupyter_server_config.py` file in the `.jupyter` > > directory, with all the defaults commented out, use the following > > command: > > > > ``` > > $ jupyter server --generate-config > > ``` > > - [Running a Jupyter Server](https://jupyter-server.readthedocs.io/en/stable/operators/public-server.html) > > - Related: [Configuring a language kernel](https://ipython.readthedocs.io/en/latest/install/kernel_install.html) > to run in the Jupyter Server enables your server to run other languages, like R or Julia. ```{warning} Jupyter Notebook 7 is now based on Jupyter Server. This may break some previous `notebook` imports you may have been using, such as `notebook.auth` or `notebook.notebookapp`. Check out the [migration guide](../migrating/server-imports.md) to learn more on how to update these server imports. ``` (configure-nbextensions)= ## Notebook extensions The Notebook frontend can be extended with JupyterLab extensions. See the {ref}`Frontend Extension Guide ` for more information. [Security in Jupyter notebooks:](https://jupyter-server.readthedocs.io/en/stable/operators/security.html) Since security policies vary from organization to organization, we encourage you to consult with your security team on settings that would be best for your use cases. Our documentation offers some responsible security practices, and we recommend becoming familiar with the practices. --- ## File: docs/source/configuring/interface_customization.md # Interface Customization Multiple elements in the Notebook interface can be customized via the Settings Editor. ## Layout By default some widgets are displayed in pre-defined parts of the user interface, which are often called "areas" or "regions". For example the table of contents will be displayed in the `left` area by default, while the debugger will be displayed in the `right` area. However the positioning of some of these components can also be customized via the Settings Editor. Below are a few examples of how to do this. ### Open the Markdown Preview on the left It is often useful to be able to see a rendered preview of a Markdown document while editing it. By default the Markdown Preview opens on the right side of the application. However it is also possible to open it on the left side by changing the Notebook Shell settings in the Advanced Settings Editor: ```json { "layout": { "Markdown Preview": { "area": "left" } } } ``` ### Configuring a third-party widget Third-party extensions can also add widgets to the application shell. This is for example the case with the [Voila extension](https://github.com/voila-dashboards/voila), which adds a preview widget to visualize a notebook as a dashboard. By default in JupyterLab the Voila Preview is added to the `main` area next to the corresponding notebook. With Notebook 7 it is possible to move the Voila Preview to the `right` area by changing the Notebook Shell setting in the Advanced Settings Editor as follows: ```json { "layout": { "Voila Preview": { "area": "right" } } } ``` ```{note} Refer to the [JupyterLab Layout Documentation](https://jupyterlab.readthedocs.io/en/latest/user/interface_customization.html#layout) to learn more about the default positioning of other UI elements. ``` ## Toolbars, Menu bar and Context Menu It is also possible to customize toolbars, menus and context menu entries via the Settings Editor. For example the items of the notebook toolbar can be reordered, or some menu entries can be hidden. ```{note} Refer to the [JupyterLab Documentation](https://jupyterlab.readthedocs.io/en/latest/user/interface_customization.html) to learn more about general interface customization via the settings editor. ``` --- ## File: docs/source/configuring/plugins.md # Managing plugins Notebook 7 uses the same extension system as JupyterLab. An extension can provide multiple plugins. ```{note} See the [JupyterLab documentation](https://jupyterlab.readthedocs.io/en/latest/user/extensions.html) to learn more about the extension system. ``` ## Examples ### Disabling the download button By default Notebook 7 provides a way to download files from the file browser. This functionality consists of a context menu entry and a main menu entry. They are provided by an application plugin that can be disabled. To disable the download entry of file browser context menus, open a terminal and run the following command: ```text jupyter labextension disable @jupyterlab/filebrowser-extension:download ``` Then restart the application and refresh the page. --- ## File: docs/source/examples/Notebook/examples_index.rst ================= Notebook Examples ================= The pages in this section are all converted notebook files. You can also `view these notebooks on nbviewer`__. __ https://nbviewer.jupyter.org/github/jupyter/notebook/blob/main/ docs/source/examples/Notebook/ .. toctree:: :maxdepth: 2 What is the Jupyter Notebook Notebook Basics Running Code Working With Markdown Cells Custom Keyboard Shortcuts Importing Notebooks Connecting with the Qt Console Typesetting Equations --- ## File: docs/source/extending/frontend_extensions.md (frontend-extensions)= # Custom front-end extensions This describes the basic steps to write a TypeScript extension for the Jupyter notebook front-end. This allows you to customize the behaviour of the various pages like the dashboard, the notebook, or the text editor. Starting with Notebook 7, front-end extensions for the notebook can be developed as prebuilt JupyterLab extensions. This means Notebook 7 is able to reuse many of the existing extensions from the JupyterLab ecosystem as is. If you would like to develop a prebuilt extension for Notebook 7, check out: - [JupyterLab Extension Tutorial](https://jupyterlab.readthedocs.io/en/latest/extension/extension_tutorial.html): A tutorial to learn how to make a simple JupyterLab extension. - The [JupyterLab Extension Examples Repository](https://github.com/jupyterlab/extension-examples): A repository containing many examples of JupyterLab extensions for performing various tasks: adding commands, adding a new widget, handling user settings, etc. --- ## File: docs/source/extending/index.md # Extending the Notebook ```{warning} Please note that the extension system for Notebook 7 is radically different from the one used in Notebook 6.5.x and earlier. If you are looking for information on how to extend the classic Notebook, please refer to the [documentation for NbClassic](https://nbclassic.readthedocs.io/en/latest/extending/index.html). ``` ```{note} With Notebook 7 being developed on top of JupyterLab and Jupyter Server, the frontend extension system is now based on the same extension system used by JupyterLab. Server extensions are also now based on the same system used by Jupyter Server. You will find below a link to the relevant documentations. ``` Certain subsystems of the notebook server are designed to be extended or overridden by users. These documents explain these systems, and show how to override the notebook's defaults with your own custom behavior. ```{toctree} :maxdepth: 2 Extending the Jupyter Server frontend_extensions ``` --- ## File: docs/source/migrating/custom-themes.md # Custom themes in Notebook 7 In Notebook 7, the way to create custom themes has changed. This means that custom themes developed for Notebook 6 or earlier will not work with Notebook 7 and upwards. This is for example the case for community contributed themes such as [jupyter-themes](https://github.com/dunovank/jupyter-themes). ## Using a custom theme Fortunately installing a custom theme for Notebook 7 is very easy. It is the same process as installing a regular extension. For example let's say you want to install the [JupyterLab Night](https://github.com/jupyterlab-contrib/jupyterlab-night) theme. You can do so by running the following command: ```bash pip install jupyterlab-night ``` Then refresh the page and you should see the new theme available in the settings menu: There are already many themes available on [PyPI](https://pypi.org/search/?q=jupyterlab-theme). You can also find other themes using the `jupyterlab-theme` topic on GitHub: https://github.com/topics/jupyterlab-theme For example: - [https://github.com/johnnybarrels/jupyterlab_onedarkpro](https://github.com/johnnybarrels/jupyterlab_onedarkpro) - [https://github.com/dunovank/jupyterlab_legos_ui](https://github.com/dunovank/jupyterlab_legos_ui) - [https://github.com/timkpaine/jupyterlab_miami_nights](https://github.com/timkpaine/jupyterlab_miami_nights) ## Creating a custom theme Creating a custom theme for Notebook 7 follows the same process as creating a custom theme for JupyterLab 4. See the {ref}`Frontend Extension Guide ` to get you started. When creating the extension, select the `Theme` option in the cookiecutter prompt. --- ## File: docs/source/migrating/frontend-extensions.md # Frontend Extensions in Notebook 7 ```{warning} Any extension developed for Notebook \< 7 or NbClassic will not be compatible with Notebook 7 and upwards. Some extensions like nbgrader have already been ported. We invite you to check if the extensions you are using have already been ported. ``` You can check the following resources to see if your extension is available for Notebook 7: ## List of available Notebook 7 extensions To get an idea of the extensions available for Notebook 7, you can check the following resources: - [List of JupyterLab extensions][list of jupyterlab extensions] - [Awesome Jupyter][awesome jupyter] These resources are for JupyterLab, but many of them are compatible with Notebook 7 since Notebook 7 is based on JupyterLab. [list of jupyterlab extensions]: https://jupyterlab-contrib.github.io/extensions.html [awesome jupyter]: https://github.com/markusschanta/awesome-jupyter#jupyterlab-extensions ## JupyterLab equivalent extensions to the Classic Notebook The `jupyterlab-contrib` organization maintains a list of extensions to ease the transition from the Classic Notebook to Notebook 7 and / or JupyterLab. The list is available at the following URL: [Migrating from the Classic Notebook][migrate from classic] [migrate from classic]: https://jupyterlab-contrib.github.io/migrate_from_classical.html --- ## File: docs/source/migrating/multiple-interfaces.md # Simultaneous usage of different versions of Notebook 7 and the Classic Notebook UI With the release of Notebook 7, the classic Notebook UI is now available as a Jupyter Server extension, NbClassic. This means that NbClassic can be installed independently of Notebook 7, and can be also installed alongside Notebook 7. Below are different scenarios that you might consider when updating to Notebook 7. ## Try it on Binder You can try JupyterLab, Notebook 7 and NBClassic installed together using [this gist][lab-nb-nbclassic] on Binder: [](https://mybinder.org/v2/gist/jtpio/35a72862c8be13dee31b61ebac2d9786/master?urlpath=/tree) [lab-nb-nbclassic]: https://gist.github.com/jtpio/35a72862c8be13dee31b61ebac2d9786 ## Using the `Interface` dropdown Notebook 7 provides a dropdown menu to switch between the different user interfaces available on the same server. It is available in the Notebook toolbar: ```{note} This dropdown is only available when using Notebook 7 or JupyterLab. It is not displayed when using NbClassic. ``` ## NbClassic and Notebook 7 You can install NbClassic, Notebook 7 and JupyterLab, all three of which will provide different user interfaces on the same server. When Notebook 7 is available, the NbClassic UI, will be served at the `/nbclassic/tree` base path rather than the base path `/tree` used otherwise. If you are using Notebook 7 along with NbClassic, you will also have JupyterLab installed as it is a dependency of Notebook 7, and these front ends will be available through the following base paths: JupyterLab at `/lab`, Notebook 7 at `/tree`, and NbClassic at `/nbclassic/tree`. ## NbClassic and Notebook 6.5.x As NbClassic provides the static assets for Notebook 6.5.x, while having both installed should cause no issues, the user interface provided by these two packages will be the same. These UIs will be served by different back end servers. An NbClassic instance will be at a server with the `/tree` path and opening a Notebook 6.5.x instance will open on a different server with the `/tree` path as well, presenting the same static assets. When starting an instance of JupyterLab you will be able to access the classic view of Notebook with NbClassic served on the same server at `/tree`. ## NbClassic and Notebook \<= 6.4.x When using NbClassic and Notebook \<= 6.4.x you can expect that these UIs will not be only presented at different servers, meaning they will both be available at their respective server under `/tree` but they may also differ as potential changes to the NbClassic UI will not be reflected in Notebook versions \<= 6.4.x. In this case as well, you would be able to access the classic view of Notebook with NbClassic served on the same server, at `/tree`. ## NbClassic and JupyterLab 3.x When only JupyterLab 3.x is installed, then NbClassic does not have to be explicitly installed as JupyterLab 3.x depends on it. They will run on the same server, and are reachable via `/tree` for NbClassic and `/lab` for JupyterLab. ## NbClassic and JupyterLab 4.x When only JupyterLab 4.x is installed, then NbClassic has to be installed explicitly. They will run on the same server, and are reachable via `/tree` for NbClassic, and `/lab` for JupyterLab. ## NbClassic Independently When you choose to install only NbClassic via `pip install nbclassic`, the classic Notebook UI will be presented at the `/tree` path. As the other frontends are not installed, attempting to access the other paths will return errors. Note that NbClassic being a Jupyter Server extension, indicated Jupyter Server will be available. This provides an additional way to view the NbClassic frontend. You would be able to manually enable the extension when running an instance of Jupyter Server, `> jupyter server --ServerApp.jpserver_extensions="nbclassic=True"`, which will provide the NbClassic frontend at `/tree` path when visited. ## 2. Official Technical Reference & Guides (jupyter/docs) # Jupyter Documentation Working Group The Docs Working Group serves as a support, helper, and advisory body to Jupyter subprojects on all aspects of documentation. The core pillars of our mission: - Improve all aspects of documentation across the Jupyter ecosystem - Make high quality documentation that is clear, comprehensive, inclusive, and serves the varying needs of Jupyter's diverse community - Engage with the community to help users with Jupyter products, discover their needs, and connect them with relevant information, expertise and resources If you'd like to contact the members, you can email [jupyter-docs-working-group@googlegroups.com](mailto:jupyter-docs-working-group@googlegroups.com). ## Welcome Everyone! The Docs Working Group welcomes everyone who wants to participate. Newcomers, writers, programmers, community members, please join us! You can find more information about participating below. ## Weekly Meetings We have videoconference meetings every week where we discuss what we have been working on and get feedback from one another. Anyone is welcome to attend, if they would like to discuss a topic or just listen in. - When: Wednesdays 8:00 AM Pacific Time (USA) - Where: [jovyan Zoom](https://zoom.us/j/95228013874?pwd%3DEp7HIk8t9JP6VToxt1Wj4P7K5PshC0.1) - What: Meeting notes ## Meeting notes (HackMD) You can find a collaborative document at HackMD used for driving meeting discussion topics, and capturing notes. Please feel free to come to the meetings and add agenda items for any items you'd like to discuss. [https://hackmd.io/Z5ITYv74Rde12drdpHW5PA](https://hackmd.io/Z5ITYv74Rde12drdpHW5PA?both) ## Existing Discussion Threads *Please add additional items here.* Read more about the Docs Working Group's founding (and related discussions) at these links: - Original discussion-issue: https://github.com/jupyterlab/team-compass/issues/212 - Jupyter Discourse post: https://discourse.jupyter.org/t/improving-documentation-tutorials-with-a-new-jupyter-working-group/21293 - Discussion in Jupyter/Governance where to place the workgroup: https://github.com/jupyter/governance/issues/184 - Ping JupyterHub community: https://github.com/jupyterhub/mybinder.org-deploy/issues/2732 & https://github.com/jupyterhub/team-compass/issues/681 - Ping Jupyter/Jupyter community: https://github.com/jupyter/jupyter/issues/699