This page is intended for people interested in building new or modified functionality for Jupyter AI.

If you would like to build applications that enhance Jupyter AI, please see the developer’s guide.

Design principles#

Maintainers of Jupyter AI have adopted principles that contributors should also follow. These principles, which build on top of the Zen of Python, are intended to earn users’ trust by keeping their data under their control. The following list is non-exhaustive; maintainers have discretion to interpret and revise these principles.

  1. Jupyter AI is vendor-agnostic. Jupyter AI does not discriminate between available models, and gives users a choice of model providers. A feature in Jupyter AI may be specific to one model or model provider if it cannot be used with other models or providers.

  2. Jupyter AI only responds to an explicit prompt; it does not watch files and it does not send prompts automatically. Any change that watches user files must be opt-in only.

  3. Jupyter AI is transparent with its chat prompts. The chat interface and magic commands use system messages and prompt templates that are open source, so that users know what gets sent to language models.

  4. Jupyter AI is traceable; users know when it has been used to generate content. When Jupyter AI generates a notebook, the notebook says that it was generated by Jupyter AI. When a user runs a Jupyter AI magic command in a notebook, output cells say, in their metadata, that they were generated by Jupyter AI.

  5. Jupyter AI uses a human-centered design. The chat interface should look and feel like chat applications that are generally available. The magic commands should look and work like other IPython magic commands. Settings screens should be used minimally, and wherever they are used, they should be readable and understandable, even for users not fluent in the user interface language.

Issues and pull requests that violate the above principles may be declined. If you are unsure about whether your idea is a good fit for Jupyter AI, please open an issue so that our maintainers can discuss it with you.


You can develop Jupyter AI on any system that can run a supported Python version up to and including 3.11, including recent Windows, macOS, and Linux versions.

Each Jupyter AI major version works with only one major version of JupyterLab. Jupyter AI 1.x supports JupyterLab 3.x, and Jupyter AI 2.x supports JupyterLab 4.x.

We highly recommend that you install conda to start developing on Jupyter AI, especially if you are developing on macOS on an Apple Silicon-based Mac (M1, M1 Pro, M2, etc.).

You will need Node.js 18 to use Jupyter AI. Node.js 18.16.0 is known to work.


Due to a compatibility issue with Webpack, Node.js 18.15.0 does not work with Jupyter AI.

Development install#

After you have installed the prerequisites, create a new conda environment and activate it.

conda create -n jupyter-ai -c conda-forge python=3.11 nodejs=20
conda activate jupyter-ai

This command must be run from the root of the monorepo (<jupyter-ai-top>).

# Move to the root of the repo package
cd <jupyter-ai-top>

# Installs all the dependencies and sets up the dev environment

Start and launch JupyterLab in your default browser:

jlpm dev

You can open a new terminal and use that to build and push changes to the repository. Enter the conda environment and build the project after making any changes.

cd <jupyter-ai-top>
conda activate jupyter-ai
jlpm build

To change what Jupyter AI packages are installed in your dev environment, use the dev-uninstall script:

# uninstalls all Jupyter AI packages
jlpm dev-uninstall

To reinstall Jupyter AI packages back into your dev environment, use the dev-install script:

# installs all Jupyter AI packages
jlpm dev-install

To only install/uninstall a subset of Jupyter AI packages, use the --scope argument that gets forwarded to Lerna:

# installs jupyter_ai_magics and its dependencies
jlpm dev-install --scope "@jupyter-ai/magics"

Making changes while your server is running#

If you change, add, or remove a magic command, after rebuilding, restart the kernel or restart the server.

If you make changes to the user interface or lab extension, run jlpm build and then refresh your browser tab.

Building documentation#

The ./scripts/ should automatically install the documentation dependencies. To build the documentation locally, run

cd docs/
make html

and open file://<JUPYTER-AI-ABSOLUTE-PATH>/docs/build/html/index.html, where <JUPYTER-AI-ABSOLUTE-PATH> is the absolute path of the Jupyter AI monorepo on your local filesystem. It is helpful to bookmark this path in your browser of choice to easily view your local documentation build.

After making any changes, make sure to rebuild the documentation locally via make html, and then refresh your browser to verify the changes visually.

Development uninstall#

To uninstall your Jupyter AI development environment, deactivate and remove the Conda environment:

conda deactivate
conda env remove -n jupyter-ai


Integration / E2E tests#

This extension uses Playwright for the integration / E2E tests (user-level tests). More precisely, the JupyterLab helper Galata is used to test the extension in JupyterLab.

Install test dependencies (needed only once):

cd ./packages/jupyter-ai/ui-tests/
jlpm install
jlpm playwright install

Tests involve snapshot comparisons against a reference snapshots generated by the Github CI. If you are using an OS other than Linux, you will need to generate local snapshots before running the tests locally for the first time. To do this, execute the command:

cd ./packages/jupyter-ai/ui-tests/
jlpm test:update

To execute tests, run:

cd ./packages/jupyter-ai/ui-tests/
jlpm test

You can find more information in the ui-tests README.