ipylab

1.1.0 · active · verified Thu Apr 16

ipylab is a Python library that allows direct control and interaction with the JupyterLab environment from within Python notebooks. It provides programmatic access to JupyterLab's features, enabling users to add widgets to the main area, build complex interfaces using Lumino widgets, launch arbitrary commands, and listen to JupyterLab signals to trigger Python callbacks. The library is currently at version 1.1.0 and is actively maintained with a focus on compatibility with recent JupyterLab and ipywidgets versions.

Common errors

```
Error: Module ipylab, semver range ^X.Y.Z is not registered as a widget module.
```
cause This error typically indicates that the JupyterLab extension for `ipylab` (or `ipywidgets`) is not properly installed, enabled, or recognized by your JupyterLab frontend.

fix Ensure that `jupyterlab` and `ipylab` (and `ipywidgets`) are installed in the same environment. If installed via `pip`, JupyterLab usually handles the frontend extension automatically, but sometimes a manual `jupyter lab build` or `jupyter labextension install @jupyter-widgets/jupyterlab-manager` might be needed for older JupyterLab versions or specific setups. Restart JupyterLab after installation.
```
ipywidgets not working / widgets not appearing (no output or only text description)
```
cause This is often caused by an incompatibility between the versions of JupyterLab and `ipywidgets`, or if the JupyterLab manager for widgets is not correctly installed or enabled.

fix Verify that your `ipywidgets` version is compatible with your JupyterLab version (e.g., `ipywidgets` 8.x for JupyterLab 4.x). Ensure `jupyterlab_widgets` is installed. Try `pip install --upgrade jupyterlab ipywidgets` and then `jupyter lab build` to refresh the frontend assets. Restart your JupyterLab server.
```
Command 'jupyter' not found
```
cause The `jupyter` command-line tool is not found in your system's PATH environment variable. This means that the shell cannot locate the executable.

fix Ensure that the directory containing the `jupyter` executable (often `~/.local/bin` for pip user installs or `<conda_env_path>/bin/` for conda) is included in your system's PATH. Alternatively, you can explicitly call the executable by its full path, e.g., `~/.local/bin/jupyter lab`.

Warnings

breaking ipylab version 1.0.0 introduced breaking changes by updating its core to be compatible with JupyterLab 4. Older JupyterLab extensions or custom code may require updates.
Fix: Ensure your JupyterLab installation is updated to version 4.x. Review the `ipylab` and JupyterLab documentation for specific migration guides if you encounter issues.
breaking ipylab version 0.6.0 updated its dependency to ipywidgets 8. This change is significant for projects relying on `ipywidgets` functionality, as API changes might be present.
Fix: Upgrade `ipywidgets` to version 8.x in your environment. Consult the `ipywidgets` migration guide for details on adapting custom widgets or older code.
breaking Support for Python 3.6 was dropped in ipylab version 0.6.0. Using `ipylab` with Python 3.6 will lead to installation failures or runtime errors.
Fix: Ensure your Python environment is running Python 3.8 or newer. Update your environment or create a new one with a supported Python version.
gotcha Jupyter Widgets (which `ipylab` leverages) might display differently or require specific rendering methods (e.g., in an `iframe`) when used in JupyterLab 4 or Notebook 7 environments.
Fix: Test your `ipylab` and `ipywidgets` usage across different JupyterLab/Notebook versions. For interactive widgets, you might need to use `IPython.display.display(IFrame(...))` with embedded HTML for consistent behavior, as described in `ipywidgets` documentation.
gotcha Mismatched versions of JupyterLab, `ipywidgets`, or the `jupyterlab_widgets` extension can lead to `ipylab` widgets not appearing or functioning correctly without explicit error messages.
Fix: Always install `ipylab` within the same `conda` or `pip` environment as your JupyterLab and `ipywidgets` installation. Ensure all packages are up-to-date or compatible according to their release notes. A fresh environment setup often resolves these issues.

Install

pip install ipylab Pip
mamba install -c conda-forge ipylab Mamba/Conda

Imports

JupyterFrontEnd
```
from ipylab import JupyterFrontEnd
```

Quickstart

This quickstart demonstrates how to instantiate the JupyterFrontEnd application object and use it to execute a JupyterLab command. A button is created using `ipywidgets`, which, when clicked, triggers the 'notebook:run-all-below' command in the active JupyterLab notebook.

from ipylab import JupyterFrontEnd
import ipywidgets as widgets
from IPython.display import display

app = JupyterFrontEnd()

def run_all(event):
    """Executes the 'notebook:run-all-below' command in JupyterLab."""
    print("Executing 'notebook:run-all-below'...")
    app.commands.execute('notebook:run-all-below')
    print("Command sent.")

button = widgets.Button(description="Run All Below")
button.on_click(run_all)

display(button)

view raw JSON →