Install & Compatibility
Where this runs
tested against v2.31.7 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.910 runs
installs and imports cleanly · install 0.0s · import 4.374s · 271.8MB
glibcpy 3.10–3.910 runs
installs and imports cleanly · install 19.5s · import 4.051s · 276MB
275MB installed
● package 275MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
AiMagics
✓ from jupyter_ai_magics.magics import AiMagics
✗ import jupyter_ai_magics
While AiMagics is the class providing the functionality, users typically load the magics in a Jupyter cell using `%load_ext jupyter_ai` rather than directly importing this class via Python.
This quickstart demonstrates how to set up environment variables for LLM providers (e.g., OpenAI), load the Jupyter AI magics extension in a Jupyter notebook cell, and then use both the line (`%ai`) and cell (`%%ai`) magics to interact with a Large Language Model. Ensure you have the necessary LLM client libraries installed (e.g., `pip install openai`) and valid API keys or a running local LLM server.
import os
# --- In a Jupyter notebook cell ---
# 1. Set your API key as an environment variable.
# For OpenAI: uncomment the line below and replace 'sk-YOUR_OPENAI_API_KEY'
# os.environ['OPENAI_API_KEY'] = os.environ.get('OPENAI_API_KEY', 'sk-dummy-for-quickstart-test')
# For local models like Ollama, ensure the server is running:
# e.g., in your terminal: `ollama run mistral`
# 2. Load the Jupyter AI magics extension.
# This makes the %ai and %%ai commands available in your notebook.
# %load_ext jupyter_ai
# 3. (Optional) List available providers and models
# %ai list
# 4. Use the %ai line magic for single-line prompts.
# Replace 'openai:gpt-3.5-turbo' with your desired model and provider.
# %ai openai:gpt-3.5-turbo "What is the capital of France?"
# 5. Use the %%ai cell magic for multi-line prompts.
# The prompt is the content of the cell after the magic.
# %%ai openai:gpt-3.5-turbo
# Write a short poem about the benefits of learning Python.
# It should be 4 lines long and rhyme AABB.
jupyter-ai --version
Debug
Known issues
gotchaLLM Provider Configuration Required: Jupyter AI needs valid API keys (e.g., OPENAI_API_KEY, ANTHROPIC_API_KEY) or a running local server (e.g., Ollama) to function. Without proper configuration, magic commands will fail with errors like 'No model selected' or 'AuthenticationError'.fixSet required API keys as environment variables before loading the magics, or ensure your local LLM server is running and accessible. Refer to the official documentation for specific provider setup instructions.
affects: All versions
gotchaKernel Restart After Installation/Config Changes: Sometimes, after installing `jupyter-ai-magics` or modifying LLM provider configurations (especially environment variables), you may need to restart your Jupyter kernel for the magics to be properly recognized and activated.fixIf magics are not found or configuration changes don't take effect, try restarting the Jupyter kernel (Kernel -> Restart Kernel... in JupyterLab/Notebook).
affects: All versions
breakingChanges to Model Naming and Provider Aliases: Early versions had slightly different provider identifiers or model names. As the project evolves, these names can be updated or new providers added, potentially breaking older scripts that hardcode specific model strings.fixAlways use `%ai list` to verify available providers and models. Update your scripts to use the current naming conventions or, for robustness, abstract model names where possible.
affects: < 2.0 (minor changes continue across major versions)
gotchaMagics Only Work in Jupyter Environments: The `%ai` and `%%ai` commands are IPython magics and will only execute correctly within a Jupyter notebook, JupyterLab, or IPython shell. Attempting to run them in a standard Python script will result in a `SyntaxError`.fixEnsure you are running your code within a Jupyter or IPython environment. For programmatic LLM interaction outside of Jupyter, use the underlying LLM client libraries directly (e.g., `openai` Python package).
affects: All versions
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'jupyter_ai'
The `jupyter-ai-magics` package or its core dependency `jupyter-ai` is not installed, or the Jupyter environment is not correctly configured to find it.
fix`pip install jupyter-ai-magics` in the same Python environment that your Jupyter server is running from. If already installed, try restarting your Jupyter kernel.
MagicsProviderError: No model selected. Please select a model using '%ai_provider <provider_id>' or '%ai --model <model_id>'
No LLM provider is configured (e.g., missing API key for OpenAI) or a specific model was not selected for the magic command.
fixSet the required API key as an environment variable (e.g., `os.environ['OPENAI_API_KEY'] = 'sk-...'`) and ensure it's available before loading the magics, or explicitly specify the model in the command, e.g., `%ai openai:gpt-3.5-turbo "..."`.
SyntaxError: invalid syntax (when running %load_ext jupyter_ai in a .py file)
IPython magic commands (like `%load_ext`) are being executed in a standard Python script (.py file) where they are not recognized.
fixRun the code within a Jupyter notebook cell, JupyterLab, or an IPython interactive session. Magic commands are not part of standard Python syntax.
openai.AuthenticationError: Incorrect API key provided: You must provide your OpenAI secret key...
The OpenAI API key provided is incorrect, expired, or missing the `sk-` prefix, or the environment variable is not set correctly.
fixVerify your `OPENAI_API_KEY` environment variable is set with a valid and active key obtained from your OpenAI dashboard. Ensure it starts with `sk-`.
Upgrade
Version history
2.31.7latest on PyPI · released Nov 25, 2025
Audit
Dependencies
jupyter-airequiredCore Jupyter AI functionality and backend logic.
openaioptionalRequired to use OpenAI models (e.g., GPT-3.5, GPT-4).
anthropicoptionalRequired to use Anthropic models (e.g., Claude).
langchainrequiredUsed internally for LLM integrations, often pulled as a dependency of jupyter-ai.