Jupyter Blog - Mehmet Bektas

Building AI Agents for JupyterLab using Notebook Intelligence

2025-02-24T18:03:00+00:00

Please note that this is not an official Jupyter subproject but an independent open-source tool for JupyterLab users who want to use GitHub Copilot as an AI coding assistant.

Notebook Intelligence (NBI) is an AI coding assistant and extensible AI framework for JupyterLab. (For an introduction to NBI see Introducing Notebook Intelligence and for basics of extending NBI see Building AI Extensions for JupyterLab blog posts.)

GitHub Copilot and other AI coding assistants are great at generating code and answering coding related questions. But they can do a lot more than generating text and code thanks to LLM features such as tool calling and AI agents. NBI provides an extensible AI framework to integrate tool calling and AI agents into JupyterLab Copilot Chat.

AI Agent extension example

What is tool calling and an AI Agent?

Tool calling is a feature of LLMs. It lets you introduce your own functions to LLM so that they can be called in response to chat prompts. LLM can convert natural language prompts to function calls with arguments. Tool calls are executed on the client side (i.e. Jupyter server) by your extension and only the function schema is provided to the LLM. Tool calling lets LLM interact with real time data, proprietary or external apps and services.

AI Agents are collections of tools that can run tasks on behalf of the user. Given a natural language prompt, LLMs can reason, create an execution plan and call multiple tools in a chain. NBI provides a framework to build these type of AI Agent integrations and handles the orchestration between LLMs and your tools.

AI Agent Extension Example

Let’s build an AI Agent for JupyterLab using Notebook Intelligence extension APIs. (The full source code for this extension is available here.) This will be an AI agent for map creation and notebook sharing. It will have the following capabilities:

Looking up geo-coordinates for an address
Showing maps centered at an address in the Copilot Chat UI
Creating notebooks that show maps centered at specified addresses
Sharing notebooks publicly using notebooksharing.space

The tasks above will be run by the AI Agent in response to natural language prompts by the user.

For this extension we will build four tools that will be integrated into JupyterLab Copilot Chat, for each of the tasks above. Tools are defined as classes derived from NBI Tool abstract class. A tool needs to implement the methods and properties defined in this base class.

Tool class provides the metadata information for the tool and implements the pre_invoke and handle_tool_call methods. pre_invoke method is called right before handle_tool_call with the tool arguments and it gives an opportunity for the tool to prompt for confirmation of the tool execution.

schema property of the Tool is the function schema based on OpenAI’s function calling schema. It lets you describe your function and its parameters as an object. A Tool is expected to return an object as response from the handle_tool_call method call.

Geo Coordinates Lookup Tool

This tool looks up geo-coordinates for an address using Nominatim library. pre_invoke method for this tool only shows a message in Chat UI before looking up for the geo-coordinates in handle_tool_call method.

class GeoCoordinateLookupTool(Tool):
    @property
    def name(self) -> str:
        return "geo_coordinate_lookup"

    @property
    def title(self) -> str:
        return "Get geo-coordinates from an address"
    
    @property
    def description(self) -> str:
        return "This is a tool that converts an address to a geo-coordinates"
    
    @property
    def schema(self) -> dict:
        return {
            "type": "function",
            "function": {
                "name": self.name,
                "description": self.description,
                "parameters": {
                    "type": "object",
                    "properties": {
                        "address": {
                            "type": "string",
                            "description": "Address to convert to geo-coordinates",
                        }
                    },
                    "required": ["address"],
                    "additionalProperties": False,
                },
            },
        }

    def pre_invoke(self, request: ChatRequest, tool_args: dict) -> Union[ToolPreInvokeResponse, None]:
        address = tool_args.get('address')
        return ToolPreInvokeResponse(
            message=f"Getting coordinates for '{address}'"
        )

    async def handle_tool_call(self, request: ChatRequest, response: ChatResponse, tool_context: dict, tool_args: dict) -> dict:
        address = tool_args.get('address')
        location = geolocator.geocode(address)
        return {"latitude": location.latitude, "longitude": location.longitude}

Get geo-coordinates tool

Map Response Generator Tool

This tool shows a map in Copilot Chat UI centered at geo-coordinates. In pre_invoke method this method only shows a notification message in Chat UI. In handle_tool_call method, this tool returns a HTMLFrame response that uses HTML to show a map centered at the requested location using Google Maps.

class MapResponseGeneratorTool(Tool):
    ...

    def pre_invoke(self, request: ChatRequest, tool_args: dict) -> Union[ToolPreInvokeResponse, None]:
        geo_coordinates = tool_args.get('geo_coordinates')
        latitude = geo_coordinates.get('latitude')
        longitude = geo_coordinates.get('longitude')
        return ToolPreInvokeResponse(
            message=f"Showing a map centered at latitude: {latitude} and longitude: {longitude}"
        )

    async def handle_tool_call(self, request: ChatRequest, response: ChatResponse, tool_context: dict, tool_args: dict) -> dict:
        geo_coordinates = tool_args.get('geo_coordinates')
        latitude = geo_coordinates.get('latitude')
        longitude = geo_coordinates.get('longitude')

        response.stream(HTMLFrameData(f"""<iframe width="100%" height="100%" frameborder="0" scrolling="no" marginheight="0" marginwidth="0" id="gmap_canvas" src="https://maps.google.com/maps?width=400&amp;height=400&amp;hl=en&amp;q={latitude},{longitude}&amp;t=&amp;z=11&amp;ie=UTF8&amp;iwloc=B&amp;output=embed"></iframe>""", height=400))
        response.finish()

        return {"result": "I showed the map"}

Below is an example prompt showing map centered at “Golden Gate Bridge, San Francisco”. Note that an address was provided to Copilot as the input but Map Response Generator Tool accepts only geo-coordinates as input. This is where LLM automatically decided that it needs to first call the Geo Coordinates Lookup Tool to get geo-coordinates for this address and then it called the Map Response Generator Tool with the geo-coordinates. LLM automatically chained multiple tools and NBI handled this chaining to get the correct response for the user’s prompt.

Map Response Generator Tool

Map Notebook Creator Tool

This tool creates a notebook centered at the specified geo-coordinates. In pre_invoke method this method only shows a notification message in Chat UI. In handle_tool_call method, the tool creates a notebook using nbformat library, saves it to disk and then opens the notebook in JupyterLab UI using the response.run_ui_command NBI method.

class MapNotebookCreatorTool(Tool):
    ...

    def pre_invoke(self, request: ChatRequest, tool_args: dict) -> Union[ToolPreInvokeResponse, None]:
        geo_coordinates = tool_args.get('geo_coordinates')
        latitude = geo_coordinates.get('latitude')
        longitude = geo_coordinates.get('longitude')
        return ToolPreInvokeResponse(
            message=f"Creating a map notebook for latitude: {latitude} and longitude: {longitude}"
        )

    async def handle_tool_call(self, request: ChatRequest, response: ChatResponse, tool_context: dict, tool_args: dict) -> dict:
        geo_coordinates = tool_args.get('geo_coordinates')
        latitude = geo_coordinates.get('latitude')
        longitude = geo_coordinates.get('longitude')

        now = dt.datetime.now()
        map_file_name = f"map_{now.strftime('%Y%m%d_%H%M%S')}.ipynb"

        nb = nbf.v4.new_notebook()
        header = """\
        ### This map notebook was created by an AI Agent using [Notebook Intelligence](https://github.com/notebook-intelligence)
        """

        install_code_cell = "%%capture\n%pip install folium"

        map_code_cell = f"""\
        import folium

        map = folium.Map(location=[{latitude}, {longitude}], zoom_start=13)
        map"""

        nb['cells'] = [
            nbf.v4.new_markdown_cell(header),
            nbf.v4.new_code_cell(install_code_cell),
            nbf.v4.new_code_cell(map_code_cell)
        ]
        nb.metadata["kernelspec"] = { "name": "python3"}
        nbf.write(nb, map_file_name)

        await response.run_ui_command("docmanager:open", {"path": map_file_name})

        return {"result": "I created and opened the map notebook"}

Map Notebook Creator Tool

This tool shares a notebook publicly by uploading it to notebooksharing.space and displays the link to the shared notebook.

In the pre_invoke method implementation, this tool asks for confirmation first as this operation is an undoable share of the notebook publicly. Only after the user confirms, handle_tool_call is executed. In handle_tool_call method the tool uploads the notebook at the notebook_file_path using nbss_upload library and then shows the link to the shared notebook on notebooksharing.space.

class NotebookShareTool(Tool):
    ...
    
    def pre_invoke(self, request: ChatRequest, tool_args: dict) -> Union[ToolPreInvokeResponse, None]:
        file_path = tool_args.get('notebook_file_path')
        file_name = path.basename(file_path)
        return ToolPreInvokeResponse(
            message=f"Sharing notebook '{file_name}'",
            confirmationTitle="Confirm sharing",
            confirmationMessage=f"Are you sure you want to share the notebook at '{file_path}'? This will upload the notebook to public internet and cannot be undone."
        )

    async def handle_tool_call(self, request: ChatRequest, response: ChatResponse, tool_context: dict, tool_args: dict) -> dict:
        file_path = tool_args.get('notebook_file_path')
        file_name = path.basename(file_path)
        share_url = nbss_upload.upload_notebook(file_path, False, False, 'https://notebooksharing.space')
        response.stream(AnchorData(share_url, f"Click here to view the shared notebook '{file_name}'"))

        return {"result": f"Notebook '{file_name}' has been shared at: {share_url}"}

Notebook Share Tool

Tool call schema definitions

It is important to define schemas of the tools clearly and disambiguate the tools as much as possible so that the LLM can invoke the proper tool based on the user prompt. LLM parses the user prompt, decides which tools to call and generates the input parameters for the call.

If current file or selection is made visible by the user, NBI can provide the file paths and content as context to the LLM. That way LLM can use those as additional context for a tool call. That is how Notebook Share Tool was able to access the current notebook file.

Tool chaining

After parsing the user prompt, LLM creates an execution plan and can call multiple tools in a chain. NBI handles this tool chaining for you. It is important to define your schemas with the chaining in mind. Consider defining matching tool outputs and inputs so that the output of a tool can be passed onto another one directly if needed.

Notice that in this extension example MapResponseGeneratorTool and MapNotebookCreatorTool both take in geo_coordinates (latitude, longitude) as input and GeoCoordinateLookupTool outputs geo_coordinates. This lets LLM to directly pass the output of GeoCoordinateLookupTool to MapResponseGeneratorTool and MapNotebookCreatorTool. It also lets a user to use an address to trigger MapResponseGeneratorTool and MapNotebookCreatorTool, because LLM knows that there is another tool it can call to generate input (geo_coordinates) from address for these tools.

Chat Participant

In NBI AI framework, AI Agents are defined as chat participants and tools are tied to specific chat participants. For our extension we create AIAgentChatParticipant as our participant (for more details on NBI extensions and chat participants see this blog). Our chat participant returns list of tools it defines from the tools property.

In handle_chat_request method our chat participant passes the request to the base ChatParticipant class to handle tool calling for us.

class AIAgentChatParticipant(ChatParticipant):
    @property
    def id(self) -> str:
        return "ai-agent"
    ...
    
    @property
    def tools(self) -> list[Tool]:
        return [GeoCoordinateLookupTool(), MapResponseGeneratorTool(), MapNotebookCreatorTool(), NotebookShareTool()]

    async def handle_chat_request(self, request: ChatRequest, response: ChatResponse, options: dict = {}) -> None:
        ...
        await self.handle_chat_request_with_tools(request, response, options)

NBI Extension

Finally we create our NBI extension class AIAgentExtension. This class basically registers our chat participant to NBI on extension activation.

class AIAgentExtension(NotebookIntelligenceExtension):
    ...

    def activate(self, host: Host) -> None:
        self.participant = AIAgentChatParticipant(host)
        host.register_chat_participant(self.participant)
        log.info("AI Agent example extension activated")

That is all there is to create an AI Agent for JupyterLab using Notebook Intelligence. The full source code for this example is available along with installation instructions for you to use as a reference and/or build on top.

I am looking forward to seeing the AI Agents built by the community. Please try the extension APIs and share your feedback using project’s GitHub issues! User feedback from the community will shape the project’s roadmap.

About the Author

Mehmet Bektas is a Senior Software Engineer at Netflix and a Jupyter Distinguished Contributor. He is the author of Notebook Intelligence, and contributes to JupyterLab, JupyterLab Desktop and several other projects in the Jupyter eco-system.

Introducing Notebook Intelligence!

2025-01-13T16:28:00+00:00

Please note that this is not an official Jupyter subproject but an independent open-source tool for JupyterLab users who want to use GitHub Copilot as an AI coding assistant.

I am thrilled to announce the release of Notebook Intelligence (NBI)! NBI is an AI coding assistant and extensible AI framework for JupyterLab. It uses GitHub Copilot under the hood and is inspired by its design principles. NBI greatly boosts the productivity of JupyterLab users with AI assistance powered by GitHub Copilot.

Generate code

Generate code, iterate on it

NBI integrates tightly with the notebook document. Using cell toolbar item “Generate code” or keyboard shortcut “Cmd + G” / “Ctrl + G”, you can launch the inline coding assistant popover to generate code cells.

Generate code popover

If the inline coding assistant is launched for a cell with existing code, then the generated code is shown in a diff view for approval.

Generate code with diff viewer

If you are not satisfied with the generated code, you can re-generate with an updated prompt. Diff viewer also lets you edit the generated code manually before accepting it.

Fix code in cell with NBI

Explain and fix code, troubleshoot errors reported

NBI adds a new sub menu to notebook cell context menu. Copilot can explain code in a cell or suggest fixes for any issues in it. Clicking these menu items opens Copilot Chat and generates a suggestion.

Copilot context menu

If the code cell has an output you can ask Copilot to explain it. If there are any errors reported, you can have Copilot to troubleshoot as well. These actions also take you to Copilot Chat interface.

Explain, fix, troubleshoot

Inline Completions

Notebook Intelligence integrates with JupyterLab’s inline completion APIs and provides code suggestions as you type in a code cell or a Python file.

Inline completions

Code suggestions are generated using GitHub Copilot. They are blazing fast and relevant to document you are working on. In addition to the code cell you are working on, the code in the surrounding cells are also used as context when generating suggestions.

Inline completions example

Copilot Chat

NBI provides a user friendly chat interface to chat with GitHub Copilot. You can ask questions related to coding.

Copilot Chat

If Copilot generates code snippets, they are rendered in a special format in a section with an action toolbar. Toolbar will have buttons to copy, insert, create new Python file and notebook from the snippet. Using these you can easily integrate the generated code into your project.

Copilot chat toolbar actions

Chat Commands

Chat interface also provides commands to generate new notebooks and Python code files based on your task described in the prompt. Commands start with “/” and a command auto-complete list is shown as you type. You can navigate between the commands using keyboard and choose a suggestion using “Enter” or “Tab” keys.

Chat command auto-complete

/newNotebook command

You can generate new notebooks from a prompt with the /newNotebook command. Notebook generation is shown interactively, a new empty notebook is created and opened, then code and markdown cells are added onto the notebook as they are generated by NBI and GitHub Copilot.

Generate notebook example

/newPythonFile command

You can also create new Python files from a prompt using the /newPythonFile command.

Generate Python file example

Getting Started with Notebook Intelligence

Notebook Intelligence is a JupyterLab extension published as a Python package. Simply install the package and restart JupyterLab. NBI will add a new sidebar item for Copilot Chat, a notebook context sub-menu, a cell toolbar item for “Generate code” and a status bar item for GitHub Copilot login status to JupyterLab UI. It will also be integrated with inline completion (AI suggestions for code completion).

pip install notebook-intelligence

Authentication with GitHub Copilot

Notebook Intelligence requires a GitHub Copilot subscription. NBI provides a user friendly interface to sign into your GitHub Copilot account from JupyterLab UI to activate access to your subscription.

GitHub Copilot authentication

Extensible Framework

Notebook Intelligence provides APIs to let developers extend its capabilities. You can add custom agents / chat participants, define tools (function calling) and add RAG capabilities to provide your own context to LLM for code / chat response generation. Stay tuned for my next blog post where I will walk you though extensibility features.

Notebook Intelligence is currently in beta and designed for Python (support for more languages coming soon). Please try it out and share your feedback and any feature requests using project’s GitHub issues! User feedback from the community will shape the project’s roadmap.

About the Author

JupyterLab Desktop UI Modes

2024-03-11T21:09:00+00:00

We are pleased to announce UI Mode features recently added to JupyterLab Desktop (JLD). JupyterLab Desktop now provides a convenient way to set the JupyterLab UI layout per project and introduces an new layout mode: “Zen Mode”.

There is now a new sub-menu under session menu, titled “UI Mode”, which lets you change the UI layout mode. You can choose one of the pre-defined modes or leave the layout management to the web app.

UI Mode menu

If you select “Zen Mode”, “Single document IDE” or “Multi document IDE” for a project, UI layout will update to the selected mode and it will also be reset to this mode next time the project is opened. Even if you made modifications to the layout using JupyterLab View menu, UI layout will still reset when the project is reopened. You can choose “Managed by web app” option if you would like the selections on View menu to persist.

“Reset to session default” option resets the UI mode to either to default of “UI Mode for opening a single file” or “UI Mode” as defined in the settings dialog (described in UI Mode configuration below) based on the number of files opened by the session.

Multi document IDE mode

This mode is the default layout mode in JupyterLab web app. Activity bar and side bar on the left, activity bar on the right and status bar are visible in this mode. Multiple documents and terminals can be opened at the same time.

Multi document IDE mode

Single document IDE mode

This mode corresponds to the “Simple Interface“ mode in JupyterLab web app. Activity bar, side bar and status bar visibilities are the same as “Multi document IDE” mode but tab bar is not shown and only one document or terminal can be open at a time.

Single document IDE mode

Zen Mode

“Zen Mode” is a newly introduced mode in JLD which simplifies “Simple Interface” further by hiding activity bars, side bars and status bar. Zen Mode is great for focusing on a notebook document. It is the new default mode for opening a single notebook or creating a new notebook in JLD.

Zen Mode

Below is a demo of “Zen Mode” in action. Notice that using menus or keyboard shortcuts you can still very easily navigate between different notebooks and terminals.

Zen Mode demo

UI Mode configuration

Default UI Mode for sessions and for opening a single notebook can be configured from the Settings dialog as shown below. Setting both options to “Manage by web app” makes JLD behave the same as the JupyterLab web app.

UI Mode configuration

Try the latest JupyterLab Desktop and share your feedback with us using project’s GitHub issues! User feedback from the community shapes the project roadmap.

For more information and updates on the project, follow us on GitHub and Jupyter Blog.

About the Author

Mehmet Bektas is a Senior Software Engineer at Netflix and a Jupyter Distinguished Contributor. He maintains and contributes to JupyterLab, JupyterLab Desktop and several other projects in the Jupyter eco-system.

Python environment management using JupyterLab Desktop CLI

2024-03-01T20:41:00+00:00

JupyterLab Desktop (JLD) CLI provides several commands and options to manage Python environments for use in the application. In my previous blog post I had covered using JLD UI to manage Python environments. You can use jlab CLI commands to do the same and for additional environment management options.

Setting up jlab CLI

JupyterLab Desktop installers for Windows and Linux create jlab CLI command as part of the installation process. On macOS, the CLI command is created at first program launch. Since this requires elevated user permissions, users may need to do a one time manual approval on macOS UI. Visit Settings dialog on macOS to verify that CLI command is installed properly.

jlab CLI status on Settings dialog

Setting up CLI is only an operation to configure the command for use in the Terminal. It doesn’t install any additional software, the functionality is already built into the desktop app.

jlab env CLI commands

“jlab env [options]” CLI commands provide environment management functionality. Below are the list of actions supported with overview of each one. Each action can have a variety of parameter options. See the Python environment management CLI documentation on JLD GitHub repo for the details on parameter options.

Under the hood, these commands use conda and pip that are available on your system. conda and pip could be pre-installed or they become available with the bundled Python environment installation.

jlab env info

This command prints app’s Python environment configuration on the system. JLD initializes this config at launch time by discovering the Python configuration on your system. These settings can be updated by using the UI or CLI commands that are listed below.

jlab env info command output

jlab env list

Lists discovered and user set Python environments available to the app. Python paths, python and jupyterlab package versions and whether it was created by JLD are also listed.

jlab env list command output

jlab env create

Creates a new Python environment and adds to the application registry, making it ready to use by the app. Environments can be created by using the bundled environment installer or by downloading packages from registry. “jupyterlab” Python package is required for compatibility with JLD and it is automatically installed in most cases. Additional Python packages and conda channels to use can also be specified.

This CLI command provides more options compared to Python environment management UI. Additional environment sources can be used. You can create an environment from a pre-archived conda-pack bundle, conda-lock file or a conda environment file in addition to options available on the UI. These source files can be local file paths on the system or remote URLs.

Using remote sources, environments can be created using archives and environment definition files created by conda-store and similar tools.

Additional list of packages can be installed on top of packages defined in an environment definition file. Below is an example of creating a numpy environment using a remote environment definition file and installing scikit-learn in addition.

jlab env create commad example

jlab env activate

Activates a Python environment in system Terminal. Environments can be activated by name or full prefix path.

jlab env set-python-envs-path

Sets Python environment install directory used when creating new environments.

jlab env set-conda-path

Sets the base conda executable path. Base conda executable is used when creating new conda environments, and running conda commands by the app.

jlab env set-conda-channels

Sets conda channels to use when installing new conda packages.

jlab env set-system-python-path

Sets Python executable path to use when creating new venv environments.

jlab env update-registry

Updates the app environment registry. This command checks all the environments registered for compatibility and fetches Python and jupyterlab versions. This action is normally done at desktop app launch.

Setting project Python environments using CLI

You can set the Python environment used for a project very easily by using the Python environment selection popup on the UI. You can also set it by using the CLI command “jlab config set”.

Below is an example command to set a project’s Python environment using jlab CLI.

jlab config set commad to set project Python path

Additional resources

For additional details on environment management CLI commands see the Python environment management CLI documentation at JupyterLab Desktop GitHub repo. Command parameters and options with plenty of examples can be found there.

JLD provides other CLI commands to launch and configure the application. Check out the CLI documentation for other available commands.

Try the latest JupyterLab Desktop and share your feedback with us using project’s GitHub issues! User feedback from the community shapes the project roadmap.

For more information and updates on the project, follow us on GitHub and Jupyter Blog.

About the Author

Python environment management in JupyterLab Desktop

2024-02-19T22:26:00+00:00

We are pleased to announce Python environment management features recently added to JupyterLab Desktop (JLD). Now you can create new Python environments and manage existing ones on your system, right from JupyterLab Desktop UI.

Python environment management dialog

Python environments and their use in JupyterLab Desktop

The standard distribution of JupyterLab is a Web Application which is available as a Python package named “jupyterlab”. JupyterLab Desktop makes installing and launching JupyterLab much easier by bundling it together with Python and other scientific computing dependencies in the form of a Python environment.

Python environments provide isolation of package installations and they let you work on different projects with different set of packages and/or package versions. JLD comes with a bundled Python environment installer and lets users install it as the default environment for the app from the UI and effortlessly. It can also use existing Python environments on a system to launch JupyterLab web app.

JupyterLab Desktop — Python environment selection

With the latest updates, JLD supports creating custom Python environments from the UI and the CLI. Bundled environment can now be installed to multiple locations, as different virtual environments. JLD also allows you to create new environments by downloading packages from conda or PyPI registries.

Why support environment management in JupyterLab Desktop?

It is common for our users to use different Python environments for different projects as they may require different set of Python packages or package versions. Also, in order to use a Python environment in JLD, certain requirements need to be satisfied, such as existence of “jupyterlab” package. These are some of the motivations behind adding support for Python environment management to JupyterLab Desktop.

Normally, creating a Python environment requires installing Python and/or conda onto the system first and getting familiar with terminal commands required to manage the environments. JLD simplifies this process by eliminating the need to make additional installations and by providing a user friendly interface, making it possible to create new environments with few UI clicks.

conda and Python are shipped with JupyterLab Desktop within its bundled environment installer. Once the bundled environment is installed then JLD can use the bundled conda and Python to create new environments without requiring any further conda/Python installation from the user.

Python environments created in JLD are compatible with the application itself and they are added to the environment registry of JLD automatically for use in sessions. This prevents dealing with compatibility issues and manually adding environments to JLD registry.

Python environment management dialog

JupyterLab Desktop now has a new dialog which lets you manage Python environments and settings. You can access this dialog by clicking “Manage Python environments” menu item on session menu (hamburger menu on top-right).

Managing existing environments

“Environments” tab lists the environments discovered on your system. If you have other compatible environments available on your system but not discovered then you can add those by clicking “Add existing” button. You can choose the Python executable path in the system dialog that will be shown and the environment will be validated and added to JLD registry. Any validation errors will be shown above the environment list.

Python environment context menu

You can hover over the environment list to see additional details on the environment such as JupyterLab version. You can access actions for each environment by clicking the menu on the right end of the row. You can copy the Python path or detailed environment info to clipboard by using the first two menu items. Clicking “Launch Terminal” opens a system terminal and activates the selected environment. You can browse the environment’s file system by clicking “Reveal in Finder/Explorer” . “Delete” action is available for environments created by JLD. It lets you remove the environment installation from your system.

Creating new environments

“Create new” tab lets you create new environments using the bundled installer or packages from registry.

“Copy of the bundled environment” installs a copy of the bundled environment in a different location on your system. You can set a name for it and the installation path will be shown below. The parent directory for new environment installations can be configured as will be shown in the sections below.

Create new environment using bundled installer

“New environment” option lets you create a new environment from scratch by downloading packages from conda or PyPI registries based on your environment type selection. In order to be compatible with JLD, “jupyterlab” Python package is installed into the environment by default. You can uncheck “Include jupyterlab” if you don’t plan to use the environment with JLD. You can install additional Python packages into the environment using “Additional Python packages” field and by entering the list of packages separated by space. The preview of the environment create command will be shown below. You can click “Show output” during installation to see the progress or to inspect the output from installer.

Create new environment using packages from registry

Newly created environments will be listed in “Environments” tab and they will be available to use in JLD sessions immediately.

Python environment settings

“Settings” tab lets you set Python environment configuration for JLD. The settings on this dialog are auto populated based on defaults or information discovered on your system.

Python environment settings

The default Python environment to use for JLD can be set on the top. This setting used to be in the “Settings dialog” and moved here.

“New Python environment install directory” defines the parent directory for newly created environments.

“conda path” is the path of conda executable to use to create new conda environments and to activate conda sub environments.

“conda channels” sets the channels to use when installing conda packages.

Python path setting at the bottom controls which Python executable to use when creating new venv environments.

When local JupyterLab Desktop sessions are created, the active environment information is shown on top-right section of the title bar. This session info button is clickable and when clicked it shows the Python environment selection popup. New features are added to this popup with the latest release.

On top row of this popup, the current Python path used in the session is shown now. There are two new buttons on the right of this path. The first one lets you restart the JupyterLab server running for the session. This could be useful to restart JupyterLab web app after installing packages, without restarting the whole app. The second button lets you copy session information to the clipboard, such as the URL of the JupyterLab server running.

Session environment info and action buttons

Now you can filter the Python environments listed on the environment select popup. As you type into the path filter field, the environments will be filtered by the match in Python path.

Filter Python environments

Clicking the gear icon next to filter input field takes you to the Python environment management dialog.

Updating bundled Python environment installation

When JupyterLab Desktop is updated, the bundled Python environment installation is not updated automatically. There wasn’t a clear indication of this out of sync installation and users had to go to Settings dialog to manually update the bundled environment.

Now with the latest version, notification badge is shown when the environment update is available and auto-update of the bundled environment installation made possible. You can configure the environment update options on “Advanced” tab of the “Settings dialog”. Note that “Update bundled environment automatically when app is updated” option will delete the existing installation and make a fresh install of the bundled environment.

Bundled environment update settings

When there is an update available for the bundled environment installation a notification badge is shown on the session title bar with a red circle over the server icon.

Bundled environment update notification badge

Also, a new action button is shown on environment selection popup on the right of the current Python path label, in orange color. You can update the bundled environment installation by simply clicking this button.

Bundled environment update button

Bundled environment updates require app restart and update is installed before the next launch of the application.

Bundled environment update progress

Coming up next!

Stay tuned for my next blog post which will be on the Python environment management using JupyterLab Desktop CLI! CLI commands provide additional options for creating Python environments such as installation using environment definition files and conda-pack bundles.

Try the latest JupyterLab Desktop and share your feedback with us using project’s GitHub issues! User feedback from the community shapes the project roadmap.

For more information and updates on the project, follow us on GitHub and Jupyter Blog.

About the Author

Introducing the new JupyterLab Desktop!

2023-02-09T10:21:00+00:00

We are pleased to announce a major update to JupyterLab Desktop which adds many new features with main focus on the user experience. JupyterLab Desktop is the cross-platform desktop application for JupyterLab and it is the quickest and easiest way to get started with Jupyter notebooks on your personal computer.

JupyterLab Desktop

Welcome Page

Users are now presented with the Welcome Page when the app is first launched. It contains links to several session create options on the left and the Jupyter News feed on the right. The news feed is populated using the Jupyter blog contents and is aimed to keep you up to date with the news and events related to Jupyter ecosystem projects. Clicking on a news item opens the blog post in browser.

Welcome Page

Sessions and Projects

With this release we are introducing the concept of sessions and projects. Sessions are representations of local project launches and connections to existing JupyterLab servers. Each JupyterLab UI window in the app is associated with a separate session and sessions can be restored with the same configuration at the next launch.

Each launch of JupyterLab in a different working directory is a separate project and projects can have their own configuration such as Python environment and UI layout. You can separate your work into different projects with their own notebook files and Python environment configuration, based on the project tasks and dependency libraries.

The “Start” section on the Welcome Page provides several options to create projects and sessions.

Start session links

New notebook and new session with one click

If you want to quickly get started with a new notebook, you can simply click the “New notebook…” link on the Welcome Page. It will automatically launch a new JupyterLab session in the default working directory using the default Python environment and create a new empty notebook to get you started.

“New session…” link on the Start section works similarly, it launches a new JupyterLab session with the same configuration as above but doesn’t create a notebook automatically.

Open files or folders from UI

In the Start section of the Welcome Page there are links to open files or folders directly from UI. You can use “Open…” to select files or folders you would like to start a new JupyterLab session with.

Open files or folders

If files are chosen, selected files’ parent directory becomes the working directory and selected files are opened in the session. This is also one of the methods to create or open a project in JupyterLab Desktop. On Windows and Linux “Open Folder…” and “Open File…” options are presented as separate items due to OS requirements.

Drag and drop support to create sessions

If you drop files or a folder onto the Welcome Page then they will be opened in a new session. Dropping a folder this way is the easiest way to get started with a new notebook project in your folder of choice. Dropping files creates a new session at their parent directory and opens them when session is up and ready.

Drag and drop folder to create session

Connect to existing JupyterLab servers

JupyterLab Desktop can connect to an existing JupyterLab server running locally or remotely. JupyterLab servers that are locally running on your computer are automatically detected and listed in the Connect dialog.

Connect dialog

Session restore

“Recent sessions” list on the Welcome Page shows the last sessions launched by the user. Clicking the items in the list restores the session whether it was a local project, single notebook file or a remote server connection. List items are ordered by the last launch time and items can be removed from the list in place by clicking the remove button on the right.

Recent sessions list

Multiple session window support

With this release we are adding support for multiple session windows. You can create a new session window by clicking the “New Window” menu item on the app menu at top right. New app launches from CLI, and double clicking .ipynb files create new session windows as well.

Create new window

Using this feature, you can now open multiple projects in different session windows side by side. If your startup mode is set to “Restore last sessions”, then your session windows will be restored at the next launch in the positions you laid them out previously.

Multiple session windows

Python environment auto discovery and user-friendly switch

JupyterLab Desktop shows the server status on the title bar of the session window. If you hover on it you will see the details of the server along with the active Python environment info such as its path and certain package versions.

Python environment selector menu

Python environments installed on your computer that are compatible with the app are now automatically discovered at launch time. Clicking on the server status button on the title bar opens the Python environment selector menu. Python environments discovered and any previously used environments will be listed in the menu. Hovering over the menu items shows additional details such as package versions.

You can also browse or enter the path of a Python executable on your computer using this menu to set the Python environment.

Once you select a new environment, JupyterLab server will be restarted using the new environment without restarting the application. The selected environment is stored as part of the project settings of the working directory and reapplied when the same project directory is opened.

Custom working directory and default Python environment

The default JupyterLab server root directory which is the default working directory of the app is set as user home directory. This default now can be changed using the Server tab of the Settings dialog. Default Python path is set as the path to the bundled Python environment. This can also be customized from the same settings tab. These two settings determine where the new notebooks are created and new JupyterLab sessions are launched by default.

Default working directory and Python environment settings

Startup mode

Welcome Page is the new default launch screen but the startup mode can be changed from the Settings dialog. “Start new session” option lets you launch with a new session in the default working directory using the default Python environment. “Restore last sessions” option lets you continue where you left off last time by restoring last active session windows.

Startup mode

Progress views with action links

New user friendly progress views are now shown while the app is busy with time consuming tasks or when errors occur. Based on the type of error, action links with resolution options are presented.

Progress views

CLI updates

With the added CLI options, you can now launch the app with a custom Python environment. You can also launch in a specific working directory and open files relative to it by using CLI. Check jlab --help command to learn more about the launch options.

CLI options

Security and privacy

We release frequent updates to JupyterLab Desktop to keep it up to date with JupyterLab core application and Electron. Following the best security practices, the app uses context isolation to prevent access to user’s computer from scripts running in the embedded browsers. Browser session data and other user data stored by the app can also be cleared from the Settings dialog now.

Clear history

Improved configuration options

JupyterLab Desktop now stores user settings, project settings and application data in separate JSON files. User settings file contains application settings such as default Python path and theme. These settings can be configured from Settings dialog in the application UI. Project settings file contains project (working directory) specific overrides of user settings. Application data file contains data used by the application, e.g. recent sessions list, news feed cache, Python environment list cache.

And more…

In addition to these major updates mentioned, this release contains several other smaller enhancements, improvements to logging and troubleshooting features, and bug fixes as well.

Try the latest JupyterLab Desktop and share your feedback with us using project’s GitHub issues! User feedback from the community shapes the project roadmap.

For more information and updates on the project, follow us on GitHub and Jupyter Blog.

About the Author

JupyterLab Desktop — 2022 recap

2022-12-13T23:07:00+00:00

JupyterLab Desktop is the cross-platform desktop application distribution of JupyterLab. It is the quickest and easiest way to get started with Jupyter notebooks, with the flexibility for advanced use cases.

JupyterLab Desktop

It has been slightly over a year since we relaunched JupyterLab Desktop. As we close the year 2022, we would like to share some of the recent updates and highlight the major features we implemented since the relaunch.

CLI and double click to launch

JupyterLab Desktop can be launched from the GUI of your operating system by clicking the application’s icon or by using the jlab command from the command line. jlab command allows you to launch the application from specific directories and open files at the specified path.

# launch in the current directory
jlab .
# launch in a directory at the relative path
jlab ../notebooks
# launch notebook at the path
jlab ../notebooks/test.ipynb

Double clicking to open notebook .ipynb files is also supported. This will launch the app in file’s parent directory and load the notebook file clicked.

Right click menu on notebook file

Custom Python environment support

The app comes bundled with a conda Python environment that includes the latest JupyterLab along with several popular Python libraries ready to use in scientific computing and data science workflows. A JupyterLab server instance is launched and used as the backend of the app using this Python environment as the default.

For more advanced use cases and specific needs, you can change the Python environment used by JupyterLab Desktop to another conda, venv, or pyenv virtual environment available on your computer.

Python environment selection dialog

Remote Server Connection

In addition to automatically launching a JupyterLab Server instance locally and using it as the backend of the application, JupyterLab Desktop can also connect to an existing JupyterLab server instance that is running remotely.

JupyterLab Desktop can connect to remote server instances that require authentication such as Single Sign-On (SSO) as well. User is presented with the login screens provided by the authentication service they are using and the data is stored securely in browser sessions. The session information can be persisted to automatically re-login on the next launch.

Remote server connection settings dialog

Theme support

JupyterLab Desktop now supports light and dark themes. User can choose light / dark or system theme option in Preferences. System theme basically applies the light / dark theme selected for the OS to the application.

Theme applied to JupyterLab view

The theme selection is applied to the JupyterLab view and dialogs of the application.

Theme applied to dialogs

Custom dialogs using jupyter-ui-toolkit

JupyterLab Desktop now uses jupyter-ui-toolkit components for its dialogs to provide a unified and modern look & feel across the application. jupyter-ui-toolkit is a UI toolkit providing UI components with theming support for Jupyter eco-system projects.

jupyter-ui-toolkit components in JupyterLab Desktop dialogs

Auto-update

JupyterLab Desktop regularly checks for available updates and notifies user for new versions. On macOS, automatic updates are supported as well. This feature automatically downloads a new version and installs it at the next launch. We are also in the process of adding auto-update support to Windows.

Upgraded to latest JupyterLab and Electron

We frequently release updates to JupyterLab Desktop to keep it in sync with JupyterLab core application and Electron. We address user issues and pain points reported in GitHub issues.

Electron related security issues are also constantly in our radar. With the latest release of v3.5.1–1, we upgraded to Electron v22 and enabled context isolation to all browser sessions. Context isolation blocks access to user’s computer from scripts running in embedded browser and provides the highest level of security for Electron apps.

If you haven’t already, try the latest JupyterLab Desktop and share your feedback with us using project’s GitHub issues! User feedback from the community shapes the project’s roadmap.

For more information and updates on the project, follow us on GitHub and Jupyter Blog.

About the Author

JupyterLab Desktop App now available!

2021-09-22T13:36:00+00:00

We are pleased to announce the release of desktop application for JupyterLab!

Standalone and self-contained

JupyterLab App is the cross-platform standalone application distribution of JupyterLab. It is a self-contained desktop application which bundles a Python environment with several popular Python libraries ready to use in scientific computing and data science workflows.

JupyterLab App running on macOS

Cross-platform

JupyterLab App works on Debian and Fedora based Linux, macOS and Windows operating systems. One-click installers are available for each platform.

You can download the installers from the project’s GitHub page.

One-click installer on macOS

Built-in Python environment

JupyterLab App is based on Electron and it runs the front-end of JupyterLab inside an embedded browser. The backend of the JupyterLab along with Python libraries are provided via a bundled conda Python environment. Libraries included in the environment are numpy, scipy, pandas, ipywidgets and matplotlib.

This is just the re-start

This release updates and modernizes the JupyterLab App after couple of years from the initial release and forms a new baseline for the new features to be built-on. Follow the project on GitHub and Jupyter Blog for updates.

We are looking forward to user feedback from the community to define project’s roadmap. Please provide your valuable input using project’s GitHub issues or by other available channels.

About the Author

Mehmet Bektas is a Senior Software Engineer at Netflix and a Jupyter Core Developer. He maintains and contributes to JupyterLab, JupyterLab Desktop and several other projects in the Jupyter eco-system.

Jupyter Blog - Mehmet Bektas

Building AI Agents for JupyterLab using Notebook Intelligence

What is tool calling and an AI Agent?

AI Agent Extension Example

Geo Coordinates Lookup Tool

Map Response Generator Tool

Map Notebook Creator Tool

Notebook Share Tool

Tool call schema definitions

Tool chaining

Chat Participant

NBI Extension

Try it out and share your feedback!

About the Author

Introducing Notebook Intelligence!

Generate code, iterate on it

Explain and fix code, troubleshoot errors reported

Inline Completions

Copilot Chat

Chat Commands

/newNotebook command

/newPythonFile command

Getting Started with Notebook Intelligence

Authentication with GitHub Copilot

Extensible Framework

Try it out and share your feedback!

About the Author

JupyterLab Desktop UI Modes

UI Mode menu

Multi document IDE mode

Single document IDE mode

Zen Mode

UI Mode configuration

Try it out and share your feedback!

About the Author

Python environment management using JupyterLab Desktop CLI

Setting up jlab CLI

jlab env CLI commands

jlab env info

jlab env list

jlab env create

jlab env activate

jlab env set-python-envs-path

jlab env set-conda-path

jlab env set-conda-channels

jlab env set-system-python-path

jlab env update-registry

Setting project Python environments using CLI

Additional resources

Try it out and share your feedback!

About the Author

Python environment management in JupyterLab Desktop

Python environments and their use in JupyterLab Desktop

Why support environment management in JupyterLab Desktop?

Python environment management dialog

Updates to Python environment selection popup

Updating bundled Python environment installation

Coming up next!

Try it out and share your feedback!

About the Author

Introducing the new JupyterLab Desktop!

Welcome Page

Sessions and Projects

New notebook and new session with one click

Open files or folders from UI

Drag and drop support to create sessions

Connect to existing JupyterLab servers

Session restore

Multiple session window support

Python environment auto discovery and user-friendly switch

Custom working directory and default Python environment

Startup mode

Progress views with action links

CLI updates

Security and privacy

Improved configuration options

And more…

Try it out and share your feedback!

About the Author

JupyterLab Desktop — 2022 recap