extensions.rst 17 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476
  1. .. _user_extensions:
  2. Extensions
  3. ==========
  4. Fundamentally, JupyterLab is designed as an extensible environment. JupyterLab
  5. extensions can customize or enhance any part of JupyterLab. They can provide
  6. new themes, file viewers and editors, or renderers for rich outputs in
  7. notebooks. Extensions can add items to the menu or command palette, keyboard
  8. shortcuts, or settings in the settings system. Extensions can provide an API
  9. for other extensions to use and can depend on other extensions. In fact, the
  10. whole of JupyterLab itself is simply a collection of extensions that are no
  11. more powerful or privileged than any custom extension.
  12. For information about developing extensions, see the :ref:`developer
  13. documentation <developer_extensions>`.
  14. .. contents:: Table of contents
  15. :local:
  16. :depth: 1
  17. Installing Extensions
  18. ---------------------
  19. A JupyterLab extension contains JavaScript that is installed into Jupyterlab and run in the browser. An extension contains one or more plugins that extend JupyterLab. There are two types of JupyterLab extensions: a *source extension* (which requires a rebuild of JupyterLab when installed), and a *prebuilt extension* (which does not require a rebuild of JupyterLab). Rebuilding JupyterLab requires Node.js to be :ref:`installed <installing_nodejs>`.
  20. JupyterLab extensions can be installed in a number of ways, including:
  21. - Python ``pip`` or ``conda`` packages can include either a source extension or a prebuilt extension. These packages may also include a server-side component necessary for the extension to function.
  22. - The Extension Manager in JupyterLab and the ``jupyter labextension install`` command can install source extension packages from `npm <https://www.npmjs.com/search?q=keywords:jupyterlab-extension>`__. Installing a source extension requires Node.js and a JupyterLab rebuild to activate. See :ref:`installing_nodejs` and :ref:`install_command`.
  23. .. _installing_nodejs:
  24. Installing Node.js
  25. ^^^^^^^^^^^^^^^^^^
  26. Source extensions require `Node.js <https://nodejs.org/>`__ to rebuild
  27. JupyterLab and activate the extension. If you use ``conda`` with
  28. ``conda-forge`` packages, you can get Node.js with:
  29. .. code:: bash
  30. conda install -c conda-forge nodejs
  31. If you use ``conda`` with default Anaconda packages (i.e., you don't normally
  32. use ``conda-forge``), you should install Node.js from the Anaconda default
  33. channel with ``conda install nodejs`` instead.
  34. You may also be able to get Node.js from your system package manager, or you
  35. can download Node.js from the `Node.js website <https://nodejs.org/>`__
  36. and install it directly.
  37. .. _install_command:
  38. Managing Extensions with ``jupyter labextension``
  39. -------------------------------------------------
  40. The ``jupyter labextension`` command enables you to install or uninstall
  41. source extensions from `npm <https://www.npmjs.com/search?q=keywords:jupyterlab-extension>`__, list all installed extensions, or disable any extension. See the help with ``jupyter labextension --help``.
  42. Installing and Uninstalling Source Extensions
  43. ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  44. You can install source extensions from `npm
  45. <https://www.npmjs.com/search?q=keywords:jupyterlab-extension>`__ with:
  46. .. code:: bash
  47. jupyter labextension install my-extension my-other-extension
  48. Use the ``my-extension@version`` syntax to install a specific version
  49. of an extension, for example:
  50. .. code:: bash
  51. jupyter labextension install my-extension@1.2.3
  52. You can also install a source extension that is not uploaded to npm, i.e.,
  53. ``my-extension`` can be a local directory containing the extension, a
  54. gzipped tarball, or a URL to a gzipped tarball.
  55. .. note::
  56. Installing a source extension will require :ref:`installing
  57. Node.js <installing_nodejs>` and require a rebuild of JupyterLab.
  58. Uninstall source extensions using the command:
  59. .. code:: bash
  60. jupyter labextension uninstall my-extension my-other-extension
  61. If you are installing/uninstalling several extensions in several stages,
  62. you may want to defer rebuilding JupyterLab by including the flag
  63. ``--no-build`` in the install/uninstall step. Once you are ready to
  64. rebuild, you can run the command:
  65. .. code:: bash
  66. jupyter lab build
  67. .. note::
  68. If you are rebuilding JupyterLab on Windows, you may encounter a
  69. ``FileNotFoundError`` due to the default path length on Windows. Node
  70. modules are stored in a deeply nested directory structure, so paths can get
  71. quite long. If you have administrative access and are on Windows 8 or 10,
  72. you can update the registry setting using these instructions:
  73. https://stackoverflow.com/a/37528731.
  74. Listing installed extensions
  75. ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  76. List all installed extensions, including those installed with ``pip`` or
  77. ``conda``, with:
  78. .. code:: bash
  79. jupyter labextension list
  80. .. note::
  81. ``jupyter labextension`` identifies an extension by its JavaScript package
  82. name, which may be different from the name of the ``pip`` or ``conda``
  83. package used to distribute the extension.
  84. .. _enable_disable_config:
  85. Enabling and Disabling Extensions
  86. ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  87. Disabling an extension prevents the all plugins in the extension from running in JupyterLab
  88. (though the code is still loaded). You can disable specific JupyterLab
  89. extensions (including core extensions) without rebuilding JupyterLab with:
  90. .. code:: bash
  91. jupyter labextension disable my-extension
  92. You can enable a disabled extension with:
  93. .. code:: bash
  94. jupyter labextension enable my-extension
  95. Installed extensions are enabled by default unless there is configuration explicity disabling them.
  96. Extensions can be disabled or enabled using the command line.
  97. Extensions or individual plugins within an extension can be disabled by another extension.
  98. The priority order for determining whether an extension is enabled or disabled is as follows:
  99. - Presence of ``<jupyter_config_path>/labconfig/pageconfig.json`` file(s) with a ``disabledExtensions`` key that is a object with package names as keys and boolean values.
  100. - (deprecated) Presence of ``disabledExensions`` key in ``<lab_app_dir>/settings/pageconfig.json``. This value is a list of extensions to disable, but is deprecated in favor of the layered configuration approach in the `labconfig` location(s).
  101. - Presence of ``disabledExtensions`` key in another JupyterLab extension's metadata that disables a given extension. The key is ignored if that extension itself is disabled.
  102. When using the command line, you can target the ``--level`` of the config: ``user``, ``system``, or ``sys-prefix`` (default).
  103. An example ``<jupyter_config_path>/labconfig/pageconfig.json`` could look as follows:
  104. .. code:: json
  105. {
  106. "disabledExtensions": {
  107. "@jupyterlab/notebook-extension": true
  108. }
  109. }
  110. See :ref:`documentation on LabConfig directories <labconfig_directories>` for more information.
  111. Managing Extensions Using the Extension Manager
  112. -----------------------------------------------
  113. You can use the Extension Manager in JupyterLab to manage extensions that are
  114. distributed as single JavaScript packages on npm.
  115. The Extension Manager is in the :ref:`left sidebar <left-sidebar>`.
  116. .. figure:: images/extension_manager_default.png
  117. :align: center
  118. :class: jp-screenshotls
  119. **Figure:** The default view has three components: a search bar, an "Installed"
  120. section, and a "Discover" section.
  121. Disclaimer
  122. ^^^^^^^^^^
  123. .. danger::
  124. Installing an extension allows it to execute arbitrary code on the server,
  125. kernel, and the browser. Therefore, we ask you to explicitly acknowledge
  126. this.
  127. By default, the disclaimer is not acknowledged.
  128. .. figure:: images/listings/disclaimer_unchecked.png
  129. :align: center
  130. :class: jp-screenshot
  131. **Figure:** User has not acknowledged the disclaimer
  132. As the disclaimer is not acknowledged, you can search for an extension,
  133. but can not install it (no install button is available).
  134. .. figure:: images/listings/disclaimer_unchecked_noinstall.png
  135. :align: center
  136. :class: jp-screenshot
  137. **Figure:** With Disclaimer unchecked, you can not install an extension
  138. To install an extension, you first have to explicitly acknowledge the disclaimer.
  139. Once done, this will remain across sessions and the user does not have to
  140. check it again.
  141. .. figure:: images/listings/disclaimer_checked.png
  142. :align: center
  143. :class: jp-screenshot
  144. **Figure:** Disclaimer checked
  145. For ease of use, you can hide the disclaimer so it takes less space on
  146. your screen.
  147. .. figure:: images/listings/disclaimer_hidden.png
  148. :align: center
  149. :class: jp-screenshot
  150. **Figure:** Disclaimer is hidden
  151. Finding Extensions
  152. ^^^^^^^^^^^^^^^^^^
  153. You can use the extension manager to find extensions for JupyterLab. To discovery
  154. freely among the currently available extensions, expand the "Discovery" section.
  155. This triggers a search for all JupyterLab extensions on the NPM registry, and
  156. the results are listed according to the `registry's sort order
  157. <https://docs.npmjs.com/searching-for-and-choosing-packages-to-download#package-search-rank-criteria>`__.
  158. An exception to this sort order is that extensions released by the Jupyter
  159. organization are always placed first. These extensions are distinguished by
  160. a small Jupyter icon next to their name.
  161. .. image:: images/extension_manager_discover.png
  162. :align: center
  163. :class: jp-screenshot
  164. :alt: Screenshot showing the discovery extension listing.
  165. Alternatively, you can limit your discovery by using the search bar. This
  166. performs a free-text search of JupyterLab extensions on the NPM registry.
  167. .. image:: images/extension_manager_search.png
  168. :align: center
  169. :class: jp-screenshot
  170. :alt: Screenshot showing an example search result
  171. Installing an Extension
  172. ^^^^^^^^^^^^^^^^^^^^^^^
  173. Once you have found a source extension that you think is interesting, install
  174. it by clicking the "Install" button of the extension list entry.
  175. .. danger::
  176. Installing an extension allows it to execute arbitrary code on the
  177. server, kernel, and in the client's browser. You should therefore
  178. avoid installing extensions you do not trust, and watch out for
  179. any extensions trying to masquerade as a trusted extension.
  180. A short while after starting the install of an extension, a drop-down should
  181. appear under the search bar indicating that the extension has been
  182. downloaded, but that a rebuild is needed to complete the installation.
  183. .. image:: images/extension_manager_rebuild.png
  184. :align: center
  185. :class: jp-screenshot
  186. :alt: Screenshot showing the rebuild indicator
  187. If you want to install/uninstall other extensions as well, you can ignore
  188. the rebuild notice until you have made all the changes you want. Once satisfied,
  189. click the 'Rebuild' button to start a rebuild in the background.
  190. Once the rebuild completes, a dialog will pop up, indicating that a reload of
  191. the page is needed in order to load the latest build into the browser.
  192. If you ignore the rebuild notice by mistake, simply refresh your browser
  193. window to trigger a new rebuild check.
  194. Managing Installed Extensions
  195. ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  196. When there are some installed extensions, they will be shown in the "Installed"
  197. section. These can then be uninstalled (if they are source extensions) or disabled. Disabling an extension will
  198. prevent it from being activated, but without rebuilding the application.
  199. Companion packages
  200. ^^^^^^^^^^^^^^^^^^
  201. During installation of an extension, JupyterLab will inspect the package
  202. metadata for any
  203. :ref:`instructions on companion packages <ext-author-companion-packages>`.
  204. Companion packages can be:
  205. - Notebook server extensions (or any other packages that need to be
  206. installed on the Notebook server).
  207. - Kernel packages. An example of companion packages for the
  208. kernel are Jupyter Widget packages, like the `ipywidgets <https://ipywidgets.readthedocs.io/en/stable>`__
  209. Python package for the
  210. `@jupyter-widgets/jupyterlab-manager package <https://www.npmjs.com/package/@jupyter-widgets/jupyterlab-manager>`__.
  211. If JupyterLab finds instructions for companion packages, it will present
  212. a dialog to notify you about these. These are informational only, and it
  213. will be up to you to take these into account or not.
  214. .. _extension_listings:
  215. Listings
  216. ^^^^^^^^
  217. When searching source extensions in the Extension Manager, JupyterLab displays the complete search result and
  218. the user is free to install any source extension. This is the :ref:`default_mode`.
  219. To bring more security, you or your administrator can enable ``blocklists`` or ``allowlists``
  220. mode. JupyterLab will check the extensions against the defined listings.
  221. .. warning::
  222. Only one mode at a time is allowed. If you or your server administrator configures
  223. both block and allow listings, the JupyterLab server will not start.
  224. .. figure:: images/listings/simultaneous_block_allow_listings.png
  225. :align: center
  226. :class: jp-screenshot
  227. **Figure:** Simultaneous block and allow listings
  228. The following details the behavior for the :ref:`blocklist_mode` and the :ref:`allowlist_mode`.
  229. The details to enable configure the listings can be read :ref:`listings_conf`.
  230. .. _default_mode:
  231. Default mode
  232. """"""""""""
  233. In the ``default`` mode, no listing is enabled and the search behavior is unchanged and
  234. is the one described previously.
  235. .. _blocklist_mode:
  236. Blocklist mode
  237. """"""""""""""
  238. Extensions can be freely downloaded without going through a vetting process.
  239. However, users can add malicious extensions to a blocklist. The extension manager
  240. will show all extensions except for those that have
  241. been explicitly added to the blocklist. Therfore, the extension manager
  242. does not allow you to install blocklisted extensions.
  243. If you, or your administrator, has enabled the blocklist mode,
  244. JupyterLab will use the blocklist and remove all blocklisted
  245. extensions from your search result.
  246. If you have installed an extension before it has been blocklisted,
  247. the extension entry in the installed list will be highlighted
  248. in red. It is recommended that you uninstall it. You can move
  249. your mouse on the question mark icon to read the instructions.
  250. .. figure:: images/listings/installed_blocklisted.png
  251. :align: center
  252. :class: jp-screenshot
  253. **Figure:** Blocklisted installed extension which should be removed
  254. .. _allowlist_mode:
  255. Allowlist mode
  256. """"""""""""""
  257. An allowlist maintains a set of approved extensions that users can freely
  258. search and install. Extensions need to go through some sort of vetting process
  259. before they are added to the allowlist. When using an allowlist, the extension manager
  260. will only show extensions that have been explicitly added to the allowlist.
  261. If you, or your administrator, has enabled the allowlist mode
  262. JupyterLab will use the allowlist and only show extensions present
  263. in the withelist. The other extensions will not be show in the search result.
  264. If you have installed an allowlisted extension and at some point
  265. in time that extension is removed from the allowlist, the extension entry
  266. in the installed list will be highlighted in red. It is recommended that
  267. you uninstall it. You can move your mouse on the question mark icon to
  268. read the instructions.
  269. .. figure:: images/listings/installed_allowlisted.png
  270. :align: center
  271. :class: jp-screenshot
  272. **Figure:** The second of the installed extensions was removed from the allowlist and should be removed
  273. .. _listings_conf:
  274. Listing Configuration
  275. """""""""""""""""""""
  276. You or your administrator can use the following traits to define the listings loading.
  277. - ``blocklist_uris``: A list of comma-separated URIs to fetch a blocklist file from
  278. - ``allowlist_uris``: A list of comma-separated URIs to fetch an allowlist file from
  279. - ``listings_refresh_seconds``: The interval delay in seconds to refresh the lists
  280. - ``listings_request_options``: The optional kwargs to use for the listings HTTP requests
  281. For example, to enable blocklist, launch the server with ``--LabServerApp.blocklist_uris=http://example.com/blocklist.json`` where ``http://example.com/blocklist.json`` is a blocklist JSON file as described below.
  282. The details for the listings_request_options are listed
  283. on `this page <https://2.python-requests.org/en/v2.7.0/api/#requests.request>`__
  284. (for example, you could pass ``{'timeout': 10}`` to change the HTTP request timeout value).
  285. The listings are json files hosted on the URIs you have given.
  286. For each entry, you have to define the `name` of the extension as published in the NPM registry.
  287. The ``name`` attribute supports regular expressions.
  288. Optionally, you can also add some more fields for your records (``type``, ``reason``, ``creation_date``,
  289. ``last_update_date``). These optional fields are not used in the user interface.
  290. This is an example of a blocklist file.
  291. .. code:: json
  292. {
  293. "blocklist": [
  294. {
  295. "name": "@jupyterlab-examples/launcher",
  296. "type": "jupyterlab",
  297. "reason": "@jupyterlab-examples/launcher is blocklisted for test purpose - Do NOT take this for granted!!!",
  298. "creation_date": "2020-03-11T03:28:56.782Z",
  299. "last_update_date": "2020-03-11T03:28:56.782Z"
  300. }
  301. ]
  302. }
  303. In the following allowlist example a ``@jupyterlab/*`` will allowlist
  304. all jupyterlab organization extensions.
  305. .. code:: json
  306. {
  307. "allowlist": [
  308. {
  309. "name": "@jupyterlab/*",
  310. "type": "jupyterlab",
  311. "reason": "All @jupyterlab org extensions are allowlisted, of course...",
  312. "creation_date": "2020-03-11T03:28:56.782Z",
  313. "last_update_date": "2020-03-11T03:28:56.782Z"
  314. }
  315. ]
  316. }