jupyterlab-env-sync 1.0.0

A JupyterLab extension

jupyterlab-env-sync

A JupyterLab 4.x extension that provides a shared service for propagating environment variables to running kernels (Python, R, Julia) and terminals.

Other extensions consume jupyterlab-env-sync via the IEnvSync token to set, reset, and query environment variables without dealing with kernel injection or terminal lifecycle directly.

Features

• Kernel propagation — injects env var changes into all running Python, R, and Julia kernels
• Terminal restart — restarts open terminals so they inherit updated variables, with a toast notification
• Startup hooks — new kernels and terminals automatically pick up overrides via IPython/R/Julia startup scripts
• Multi-extension support — multiple consumer extensions can set variables independently; ownership is tracked per key
• Spawner-aware reset — resetting a variable restores the original spawner value (or deletes it if none existed)

Requirements

• JupyterLab >= 4.0.0
• Python >= 3.8

Installation

pip install jupyterlab-env-sync

API

Consumer extensions depend on the IEnvSync token:

import { IEnvSync } from 'jupyterlab-env-sync';

const plugin: JupyterFrontEndPlugin<void> = {
  id: 'my-extension:plugin',
  autoStart: true,
  requires: [IEnvSync],
  activate: async (app: JupyterFrontEnd, envSync: IEnvSync) => {
    await envSync.setVar(
      'my-extension',
      'DATABASE_URL',
      'postgres://localhost/mydb'
    );
  }
};

Methods

Method	Signature	Description
setVar	(extId, key, value) → Promise<void>	Set a variable. Propagates to all kernels and restarts terminals.
resetVar	(extId, key, force?) → Promise<void>	Reset to spawner value. Only the owner can reset unless force=true.
getAll	() → Promise<Record<string, IEnvEntry>>	All overrides with metadata (value, spawner_value, set_by, set_at).
getByExtension	(extId) → Promise<Record<string, string>>	Variables owned by a specific extension (key-value pairs).
resetAllByExtension	(extId) → Promise<void>	Reset all variables owned by an extension.

Consumer package.json

{
  "dependencies": {
    "jupyterlab-env-sync": "^1.0.0"
  },
  "jupyterlab": {
    "sharedPackages": {
      "jupyterlab-env-sync": { "bundled": false, "singleton": true }
    }
  }
}

bundled: false and singleton: true are required so all extensions share the same IEnvSync token instance.

Development

Development Installation

# Clone the repository
git clone https://github.com/aristide/jupyterlab-env-sync.git
cd jupyterlab-env-sync

# Set up a virtual environment
virtualenv .venv
source .venv/bin/activate

# Install in development mode
pip install -e ".[test]"

# Link the extension with JupyterLab
jupyter labextension develop . --overwrite

# Enable the server extension
jupyter server extension enable jupyterlab-env-sync

# Build the TypeScript source
jlpm build

Running Tests

# Python tests (env store + REST handlers)
pytest jupyterlab-env-sync/tests/ -v

# TypeScript tests (kernel injection snippets)
jlpm test

# UI tests (requires Playwright)
cd ui-tests && jlpm install && npx playwright test

Development Uninstallation

jupyter server extension disable jupyterlab-env-sync
pip uninstall jupyterlab-env-sync

License

BSD-3-Clause