A terminal for JupyterLite.

• JupyterLite >= 0.7.0, < 0.8.0

To install the extension, execute:

pip install jupyterlite-terminal

You will also need to install the JupyterLite CLI:

python -m pip install jupyterlite-core

After installing jupyterlite-core and jupyterlite-terminal, create a jupyter-lite.json file with the following content to activate the terminal extension:

{
  "jupyter-lite-schema-version": 0,
  "jupyter-config-data": {
    "terminalsAvailable": true
  }
}

Then build a new JupyterLite site:

jupyter lite build

Besides the interactive terminal, the extension registers JupyterLab commands that run commands in a headless cockle shell: one that captures the output and exit code without opening a terminal widget. These are useful for other extensions or automation that need to run shell commands in JupyterLite.

Run a single command (a throwaway shell is created and disposed automatically):

const result = await app.commands.execute(
  '@jupyterlite/terminal:execute-shell',
  {
    code: 'echo hello'
  }
);
console.log(result.exitCode); // 0
console.log(result.output); // hello

Pass a shellName to reuse a shell across calls so state such as the working directory persists:

const { shellName } = await app.commands.execute(
  '@jupyterlite/terminal:start-shell'
);
await app.commands.execute('@jupyterlite/terminal:execute-shell', {
  code: 'cd /drive',
  shellName
});
const result = await app.commands.execute(
  '@jupyterlite/terminal:execute-shell',
  {
    code: 'pwd',
    shellName
  }
);
console.log(result.output); // /drive

Each command runs as a single cockle pipeline, so |, ; and redirections (>, >>, 2>, <) work, but &&/||, command substitution and $VAR expansion are not supported.

Each jupyterlite-terminal release is built against a specific version of cockle. If you need to include imports from both jupyterlite-terminal and cockle, such as if you are implementing cockle external commands, you should ensure that you are using the correct version combination.

Note: You will need NodeJS to build the extension package.

The jlpm command is JupyterLab's pinned version of yarn that is installed with JupyterLab. You may use yarn or npm in lieu of jlpm below.

# Clone the repo to your local environment
# Change directory to the jupyterlite_terminal directory
# Install package in development mode
pip install -e "."
# Link your development version of the extension with JupyterLab
jupyter labextension develop . --overwrite
# Rebuild extension Typescript source after making changes
jlpm build

You can watch the source directory and run JupyterLab at the same time in different terminals to watch for changes in the extension's source and automatically rebuild the extension.

# Watch the source directory in one terminal, automatically rebuilding when needed
jlpm watch
# Run JupyterLab in another terminal
jupyter lab

Then build a JupyterLite distribution with the extension installed:

cd deploy
jupyter lite build --contents contents

And serve it either using:

npx static-handler _output/

or:

jupyter lite serve

To enable use of SharedArrayBuffer rather than ServiceWorker for stdin you will have to configure your server to add the Cross-Origin-Embedder-Policy and Cross-Origin-Opener-Policy headers. Do this using either:

npx static-handler --cors --coop --coep --corp _output/

or:

jupyter lite serve --LiteBuildConfig.extra_http_headers=Cross-Origin-Embedder-Policy=require-corp --LiteBuildConfig.extra_http_headers=Cross-Origin-Opener-Policy=same-origin

The project documentation includes a demo deployment, and is built on every PR so that the changes can be checked manually before merging. To build the documentation and demo locally use:

micromamba create -f docs/environment-docs.yml
micromamba activate terminal-docs
pip install -v .
cd docs
make html

To serve this locally use:

cd _build/html
python -m http.server

See RELEASE