Tutorials#

Learn how to write JupyterLab extensions with these guides:

• Extension Tutorial: A tutorial to learn how to make a simple JupyterLab extension.

• Making Extensions Compatible with Multiple Applications TutorialA tutorial for making extensions that work in both JupyterLab, Jupyter Notebook 7+ and more

• TheJupyterLab Extension Examples Repository: A short tutorial series to learn how to develop extensions for JupyterLab by example.

• Common Extension Points: A list of the most common JupyterLab extension points.

• Another common pattern for extending JupyterLab document widgets with application plugins is covered inDocuments.

Extension template#

We provide several templates to create JupyterLab extensions:

• extension-template: Create a JupyterLab extension usingcopier

• [DEPRECATED]extension-cookiecutter-ts: Create a JupyterLab extension usingcookiecutter (use the copier template instead).

API Reference Documentation#

Here is some autogenerated API documentation for JupyterLab and Lumino packages:

• JupyterLab API Documentation

• Lumino API Documentation

Application Plugins#

An application plugin is a JavaScript object with a number of metadata fields. A typical application plugin might look like this in TypeScript:

constplugin:JupyterFrontEndPlugin<MyToken>={id:'my-extension:plugin',description:'Provides a new service.',autoStart:true,requires:[ILabShell,ITranslator],optional:[ICommandPalette],provides:MyToken,activate:activateFunction};

Theid andactivate fields are required and the other fields may be omitted. For more information about how to use therequires,optional, orprovides fields, seePlugins Interacting with Each Other.

• id is a required unique string. The convention is to use the NPM extension package name, a colon, then a string identifying the plugin inside the extension.

• description is an optional string. It allows to document the purpose of a plugin.

• autostart indicates whether your plugin should be activated at application startup. Typically this should betrue. If it isfalse or omitted, your plugin will be activated when any other plugin requests the token your plugin is providing.

• requires andoptional are lists oftokens corresponding to services other plugins provide. These services will be given as arguments to theactivate function when the plugin is activated. If arequires service is not registered with JupyterLab, an error will be thrown and the plugin will not be activated.

• provides is thetoken associated with the service your plugin is providing to the system. If your plugin does not provide a service to the system, omit this field and do not return a value from youractivate function.

• activate is the function called when your plugin is activated. The arguments are, in order, theapplication object, the services corresponding to therequires tokens, then the services corresponding to theoptional tokens (ornull if that particularoptional token is not registered in the system). If aprovides token is given, the return value of theactivate function (or resolved return value if a promise is returned) will be registered as the service associated with the token.

• deactivate is the optional deactivation method

For more information, see the API reference forJupyterFrontEndPlugin.

Plugins Interacting with Each Other#

(The Provider-Consumer pattern is explained here)

One of the foundational features of the JupyterLab plugin system is that application plugins can interact with other plugins by providing a service to the system and requiring services provided by other plugins. A service can be any JavaScript value, and typically is a JavaScript object with methods and data attributes. For example, the core plugin that supplies the JupyterLab main menu provides aMain Menu service object to the system with a method to add a new top-level menu and attributes to interact with existing top-level application menus.

In the following discussion, the plugin that is providing a service to the system is theprovider plugin, and the plugin that is requiring and using the service is theconsumer plugin. Note that these kinds ofprovider andconsumer plugins are fundamental parts of JupyterLab’s Provider-Consumer pattern (which is a type ofdependency-injection pattern).

MIME Renderer Plugins#

MIME Renderer plugins are a convenience for creating a pluginthat can render mime data in a notebook and files of the given mime type. MIME renderer plugins are more declarative and more restricted than standard plugins.A mime renderer plugin is an object with the fields listed in theIExtensionobject.

JupyterLab has apdf mime renderer extension, for example. In core JupyterLab, this is used to view pdf files and view pdf data mime data in a notebook.

We have aMIME renderer example walking through creating a mime renderer extension which adds mp4 video rendering to JupyterLab. Theextension template supports MIME renderer extensions.

The mime renderer can update its data by calling.setData() on themodel it is given to render. This can be used for example to add apng representation of a dynamic figure, which will be picked up by anotebook model and added to the notebook document. When usingIDocumentWidgetFactoryOptions,you can update the document model bycalling.setData() with updated data for the rendered MIME type. Thedocument can then be saved by the user in the usual manner.

Theme plugins#

A theme is a special application plugin that registers a theme with theThemeManager service. Theme CSS assets are specially bundled in an extension (seeTheme path) so they can be unloaded or loaded as the theme is activated. Since CSS files referenced by thestyle orstyleModule keys are automatically bundled and loaded on the page, the theme files should not be referenced by these keys.

The extension package containing the theme plugin must include all static assets that are referenced by@import in its theme CSS files. Local URLs can be used to reference files relative to the location of the referring sibling CSS files. For exampleurl('images/foo.png') orurl('../foo/bar.css') can be used to refer local files in the theme. Absolute URLs (starting with a/) or external URLs (e.g.https:) can be used to refer to external assets.

See theJupyterLab Light Theme for an example.

See theTypeScript extension template (choosingtheme askind ) for a quick start to developing a theme plugin.

Service Manager Plugins#

The Service Manager is a core component of a JupyterLab application and the interface to the Jupyter Server REST API.Before JupyterLab 4.4.0, the Service Manager had to be created as a singleton object and passed when creating a JupyterLab application object.This was not convenient if some extensions needed to change the behavior of some of the core services provided by the Service Manager,as they would have to build a new JupyterLab application from scratch.

The Service Manager plugins can be provided by third-party extensions via the following tokens:

• IConnectionStatus: The connection status service.

• IContentsManager: The contents manager service, responsible for managing files and directories.

• IDefaultDrive: The default drive service, responsible for providing the default drive in which the contents manager operates.

• IServerSettings: The server settings service, defining a set of default server settings.

• IEventManager: The event manager service for emitting events that are broadcast by an event bus managed by Jupyter Server.

• IKernelManager: The kernel manager service.

• IKernelSpecManager: The kernel spec manager service.

• INbConvertManager: The nbconvert manager service, used for exports in various formats.

• ISessionManager: The session manager service.

• ISettingManager: The setting manager service, for managing user settings.

• ITerminalManager: The terminal manager service.

• IUserManager: The user manager service.

• IWorkspaceManager: The workspace manager service, to interact with the workspace API.

The following example shows how you can provide a custom contents manager service, which logs the path of the requested content in the console:

import{Contents,ContentsManager,IContentsManager,ServiceManagerPlugin}from'@jupyterlab/services';classCustomContentsextendsContentsManager{asyncget(path:string,options?:Contents.IFetchOptions):Promise<Contents.IModel>{console.log('CustomContents.get',path);returnsuper.get(path,options);}}constplugin:ServiceManagerPlugin<IContentsManager>={id:'my-extension:contents-manager',autoStart:true,provides:IContentsManager,description:'A JupyterLab extension providing a custom contents manager',activate:(_:null):Contents.IManager=>{returnnewCustomContents();}};exportdefaultplugin;

Application Plugins#

Thejupyterlab.extension field signifies that the package exports one or more JupyterLab application plugins. Set the value totrue if the default export of the main package module (i.e., the file listed in themain key ofpackage.json) is an application plugin or a list of application plugins. If your plugins are exported as default exports from a different module, set this to the relative path to the module (e.g.,"lib/foo"). Example:

"jupyterlab":{"extension":true}

MIME Renderer Plugins#

Thejupyterlab.mimeExtension field signifies that the package exports mime renderer plugins. Like thejupyterlab.extension field, the value can be a boolean (indicating a mime renderer plugin or list of mime renderer plugins is the default export from themain field), or a string, which is the relative path to the module exporting (as the default export) one or more mime renderer plugins.

Theme path#

Theme plugin assets (e.g., CSS files) need to bundled separately from a typical application plugin’s assets so they can be loaded and unloaded as the theme is activated or deactivated. If an extension exports a theme plugin, it should give the relative path to the theme assets in thejupyterlab.themePath field:

"jupyterlab":{"extension":true,"themePath":"style/theme.css"}

An extension cannot bundle multiple theme plugins.

Ensure that the theme path files are included in thefiles metadata inpackage.json. If you want to use SCSS, SASS, or LESS files, you must compile them to CSS and pointjupyterlab.themePath to the CSS files.

Plugin Settings#

JupyterLab exposes a plugin settings system that can be used to providedefault setting values and user overrides. A plugin’s settings are specified with a JSON schema file. Thejupyterlab.schemaDir field inpackage.json gives the relative location of the directory containing plugin settings schema files.

The setting system relies on plugin ids following the convention<source_package_name>:<plugin_name>. The settings schema file for the pluginplugin_name is<schemaDir>/<plugin_name>.json.

For example, the JupyterLabfilebrowser-extension package exports the@jupyterlab/filebrowser-extension:browser plugin. In thepackage.json for@jupyterlab/filebrowser-extension, we have:

"jupyterlab":{"schemaDir":"schema",}

The file browser setting schema file (which specifies some default keyboard shortcuts and other settings for the filebrowser) is located inschema/browser.json (seehere).

See thefileeditor-extensionfor another example of an extension that uses settings.

Please ensure that the schema files are included in thefiles metadata inpackage.json.

When declaring dependencies on JupyterLab packages, use the^ operator before a package version so that the build system installs the newest patch or minor version for a given major version. For example,^4.0.0 will install version 4.0.0, 4.0.1, 4.1.0, etc.

A system administrator or user can override default values provided in a plugin’s settings schema file with theoverrides.json file.

Disabling other extensions#

Thejupyterlab.disabledExtensions field gives a list of extensions or plugins to disable when this extension is installed, with the same semantics as thedisabledExtensions field ofpage_config.json. This is useful if your extension overrides built-in extensions. For example, if an extension replaces the@jupyterlab/filebrowser-extension:share-file plugin tooverride the “Copy Shareable Link” functionality in the file browser, it can automatically disable the@jupyterlab/filebrowser-extension:share-file plugin with:

"jupyterlab":{"disabledExtensions":["@jupyterlab/filebrowser-extension:share-file"]}

To disable all plugins in an extension, give the extension package name, e.g.,"@jupyterlab/filebrowser-extension" in the above example.

Deduplication of Dependencies#

Thejupyterlab.sharedPackages field controls how dependencies are bundled, shared, and deduplicated with prebuilt extensions.

One important concern and challenge in the JupyterLab extension system is deduplicating dependencies of extensions instead of having extensions use their own bundled copies of dependencies. For example, the Lumino widgets system on which JupyterLab relies for communication across the application requires all packages use the same copy of the@lumino/widgets package.Tokens identifying plugin services also need to be shared across the providers and consumers of the services, so dependencies that export tokens need to be deduplicated.

JupyterLab automatically deduplicates the entire dependency tree between source extensions when it rebuilds itself during a source extension installation. Deduplication between source and prebuilt extensions, or between prebuilt extensions themselves, is a more nuanced problem (for those curious about implementation details, this deduplication in JupyterLab is powered by the Webpack 5.0module federation system). JupyterLab comes with a reasonable default strategy for deduplicating dependencies for prebuilt extensions. Thejupyterlab.sharedPackages object in an extension’spackage.json enables an extension author to modify the default deduplication strategy for a given dependency with three boolean options. The keys of this object are dependency package names, and the values are eitherfalse (signifying that dependency should not be shared/deduplicated), or objects with up to three fields:

• bundled: iftrue (default), the dependency is bundled with the extension and is made available as one of the copies available to JupyterLab. Iffalse, the dependency is not bundled with the extension, so the extension will use a version of the dependency from a different extension.

• singleton: iftrue, the extension will always prefer to use the copy of the dependency that other extensions are using, rather than using the highest version available. The default isfalse.

• strictVersion: iftrue, the extension will always make sure the copy of the dependency it is using satisfies the dependency version range it requires.

By default, JupyterLab deduplicates direct dependencies of prebuilt extensions with direct dependencies of other source and prebuilt extensions, choosing the highest version of a dependency available to JupyterLab. JupyterLab chooses reasonable default options when using tokens and services from core JupyterLab packages. We suggest the followingsharedPackages configurations when using tokens provided by packages other than core JupyterLab packages (seePlugins Interacting with Each Other for more details about using tokens).

"jupyterlab":{"sharedPackages":{"token-package":{"singleton":true}}}

"jupyterlab":{"sharedPackages":{"token-package":{"bundled":false,"singleton":true}}}

"jupyterlab":{"sharedPackages":{"token-package":{"singleton":true}}}

Companion packages#

If your extension depends on the presence of one or more packages in thekernel, or on a notebook server extension, you can add metadata to indicatethis to the extension manager by adding metadata to your package.json file.The full options available are:

"jupyterlab":{"discovery":{"kernel":[{"kernel_spec":{"language":"<regexp for matching kernel language>","display_name":"<regexp for matching kernel display name>"//optional},"base":{"name":"<the name of the kernel package>"},"overrides":{//optional"<manager name, e.g. 'pip'>":{"name":"<name of kernel package on pip, if it differs from base name>"}},"managers":[//listofpackagemanagersthathaveyourkernelpackage"pip","conda"]}],"server":{"base":{"name":"<the name of the server extension package>"},"overrides":{//optional"<manager name, e.g. 'pip'>":{"name":"<name of server extension package on pip, if it differs from base name>"}},"managers":[//listofpackagemanagersthathaveyourserverextensionpackage"pip","conda"]}}}

A typical setup for e.g. a jupyter-widget based package will then be:

"keywords":["jupyterlab-extension","jupyter","widgets","jupyterlab"],"jupyterlab":{"extension":true,"discovery":{"kernel":[{"kernel_spec":{"language":"^python",},"base":{"name":"myipywidgetspackage"},"managers":["pip","conda"]}]}}

Currently supported package managers arepip andconda.

Extension CSS#

If your extension has a top-levelstyle key inpackage.json, the CSS file it points to will be included on the page automatically.

A convention in JupyterLab for deduplicating CSS on the page is that if your extension has a top-levelstyleModule key inpackage.json giving a JavaScript module that can be imported, it will be imported (as a JavaScript module) instead of importing thestyle key CSS file as a CSS file.

package.json metadata#

In addition to the package metadata forsource extensions, prebuilt extensions have extrajupyterlab metadata.

• outputDir:Output Directory

• webpackConfig:Custom webpack config

"jupyterlab":{"outputDir":"mypackage/labextension"}

"jupyterlab":{"webpackConfig":"./webpack.config.js"}

module.exports={experiments:{topLevelAwait:true,asyncWebAssembly:true}};

Developing a prebuilt extension#

Build a prebuilt extension using thejupyterlabextensionbuild command. This command uses dependency metadata from the active JupyterLab to produce a set of files from a source extension that comprise the prebuilt extension. The files include a main entry pointremoteEntry.<hash>.js, dependencies bundled into JavaScript files,package.json (with some extra build metadata), as well as plugin settings and theme directory structures if needed.

While authoring a prebuilt extension, you can use thelabextensiondevelop command to create a link to your prebuilt output directory, similar topipinstall-e:

jupyterlabextensiondevelop.--overwrite

Then rebuilding your extension and refreshing JupyterLab in the browser should pick up changes in your prebuilt extension source code.

If using Windows, you may need to configure your operating system for thedevelop command described above to work, please see the note:Important for Windows users

If you are developing your prebuilt extension against the JupyterLab source repo, you can run JupyterLab withjupyterlab--dev-mode--extensions-in-dev-mode to have the development version of JupyterLab load prebuilt extensions. It would be best if you had in mind that the JupyterLab packages that your extension depends on may differ from those published; this means that your extension doesn’t build with JupyterLab dependencies from your node_modules folder but those in JupyterLab source code.

If you are using TypeScript, the TypeScript compiler would complain because the dependencies of your extension may differ from those in JupyterLab. For that reason, you need to add to yourtsconfig.json the path where to search for these dependencies by adding the optionpaths:

{"compilerOptions":{"baseUrl":".","paths":{"@jupyterlab/*":["../jupyterlab/packages/*"],"*":["node_modules/*"]}}}

When adding the path to find JupyterLab dependencies, it may cause troubles with other dependencies (like lumino or react) in your project because JupyterLab packages will take its dependencies from JupyterLabnode_modules folder. In contrast, your packages will take them from yournode_modules folder. To solve this problem, you’ll need to add the dependencies with conflicts toresolutions in yourpackage.json. This way, both projects (JupyterLab and your extension) use the same version of the duplicated dependencies.

We provide aextension template that handles all of the scaffolding for an extension author, including the shipping of appropriate data files, so that when the user installs the package, the prebuilt extension ends up inshare/jupyter/labextensions

Distributing a prebuilt extension#

Prebuilt extensions can be distributed by any system that can copy the prebuilt assets into an appropriate location where JupyterLab can find them. Theofficial extension template shows how to distribute prebuilt extensions via Python pip or conda packages. A system package manager, or even just an administrative script that copies directories, could be used as well.

To distribute a prebuilt extension, copy itsoutput directory to a location where JupyterLab will find it, typically<sys-prefix>/share/jupyter/labextensions/<package-name>, where<package-name> is the JavaScript package name in thepackage.json. For example, if your JavaScript package name is@my-org/my-package, then the appropriate directory would be<sys-prefix>/share/jupyter/labextensions/@my-org/my-package.

The JupyterLab server makes thestatic/ files available via a/labextensions/ server handler. The settings and themes handlers in the server also load settings and themes from the prebuilt extension directories. If a prebuilt extension has the same name as a source extension, the prebuilt extension is preferred.

{"packageManager":"python","packageName":"mypackage","uninstallInstructions":"Use your Python package manager (pip, conda, etc.) to uninstall the package mypackage"}

Framework::JupyterFramework::Jupyter::JupyterLabFramework::Jupyter::JupyterLab::1Framework::Jupyter::JupyterLab::2Framework::Jupyter::JupyterLab::3Framework::Jupyter::JupyterLab::4Framework::Jupyter::JupyterLab::ExtensionsFramework::Jupyter::JupyterLab::Extensions::MimeRenderersFramework::Jupyter::JupyterLab::Extensions::PrebuiltFramework::Jupyter::JupyterLab::Extensions::Themes

# setup.pysetup(# the rest of the package's metadata# ...classifiers=["Framework :: Jupyter","Framework :: Jupyter :: JupyterLab","Framework :: Jupyter :: JupyterLab :: 3","Framework :: Jupyter :: JupyterLab :: Extensions","Framework :: Jupyter :: JupyterLab :: Extensions :: Prebuilt","Framework :: Jupyter :: JupyterLab :: Extensions :: Themes",])