Skip to content

run-ai/jupyterlab_genv

Repository files navigation

GPU Environment Management for JupyterLab Join the community at https://join.slack.com/t/genvcommunity/shared_invite/zt-1i70tphdc-DmFgK5yr3HFI8Txx1yFXBw Join the chat at https://gitter.im/run-ai-genv/community

Github Actions Status

A JupyterLab extension for managing GPU environments using genv.

The genv extension lets you interactively control, configure and monitor the GPU resources that your Jupyter Notebooks are using.

Overview

🏃🏻 Be an early runner in the genv community!

Join our Slack channel with the creators of genv and start building your models faster!

  • Installation and setup support as well as best practice tips and tricks directly for your use-case
  • Discuss possible features
  • Monthly coffee breaks to get to know the rest of the community

Looking forward to seeing you as a part of the community!

Table of Contents

Getting Started

Read the genv reference to get started.

Installation

Requirements

JupyterLab >= 3.0

Conda

If you are using Conda, it is best to install the jupyterlab_genv package from the channel conda-forge:

conda install -c conda-forge jupyterlab_genv

Pip

Alternatively, you can install jupyterlab_genv from PyPI using pip:

pip install jupyterlab_genv

Install genv Kernels

After installing jupyterlab_genv, you will need to install genv Jupyter kernels using:

python -m jupyterlab_genv install

Usage

Activate Your Environment

To activate your environment, you will have to select a genv kernel.

Then, click the GPUs button on the Jupyter Notebook toolbar. A dialog should pop up where you can choose either to create a new environment for your Jupyter Notebook, or to use an existing one.

Then, you can open a terminal activated in your environment. From there you will be able to configure the environment and attach devices.

Activate

Attach GPUs to Your Environment

Configuring the environment and attaching devices is done from the genv terminal.

Make sure to restart your kernel after running the command in the terminal for it to take effect.

Attach

See Devices and Environments

You can open the devices and environments widgets to see information.

Open the command palette (Command/Ctrl Shift C) and type GPUs.

Commands

Development

Setup

You will need to create a virtual environment once using the command:

conda create -n jupyterlab_genv --override-channels --strict-channel-priority -c conda-forge -c nodefaults jupyterlab=3 cookiecutter nodejs jupyter-packaging git

Then, activate the virtual environment when you want to work on the project:

conda activate jupyterlab_genv

Install

Use the following commands to install the Python package and enable it in JupyterLab:

# Install package in development mode
pip install -e .
# Link your development version of the extension with JupyterLab
jupyter labextension develop . --overwrite
# Server extension must be manually installed in develop mode
jupyter server extension enable jupyterlab_genv

If you make any changes you will need to rebuild the extension Typescript source using:

jlpm build

Alternatively, you can watch the source directory using:

jlpm watch

With the jlpm watch command running, every saved change will immediately be built locally and available in your running JupyterLab. Refresh JupyterLab to load the change in your browser (you may need to wait several seconds for the extension to be rebuilt).

Run

Run JupyterLab using the command:

jupyter lab

Running SHELL=bash jupyter lab --no-browser is even better

Uninstall

# Server extension must be manually disabled in develop mode
jupyter server extension disable jupyterlab_genv
pip uninstall jupyterlab_genv

In development mode, you will also need to remove the symlink created by jupyter labextension develop command. To find its location, you can run jupyter labextension list to figure out where the labextensions folder is located. Then you can remove the symlink named jupyterlab_genv within that folder.

Reference

List all kernel provisioners

jupyter kernelspec provisioners

Install a kernel provisioner

To add a kernel provisioner to a kernel spec, edit its kernel.json file. For example, to install a kernel provisioner for the python3 kernel spec, run:

vim $CONDA_PREFIX/share/jupyter/kernels/python3/kernel.json

And add:

"metadata": {
  "kernel_provisioner": {
    "provisioner_name": "genv-provisioner"
  }
}

List all available kernel specs

ls -la $CONDA_PREFIX/share/jupyter/kernels/

List all running kernels

ls -la $(jupyter --runtime-dir)/kernel-*.json

List Jupyter server extensions

jupyter server extension list

List JupyterLab extensions

jupyter labextension list

Publish

The jupyterlab_genv package is manually published to both PyPI and conda-forge.

We do not publish the frontend part as an npm package because the Python package is a prebuilt server extension, and the frontend part alone is useless.

Also make sure to update the changelog (here's how) and lint the project by running npm run lint.

Bump Version

The cookiecutter template uses tbump for bumping the version. However, for some reason this does not work at the moment, and we bump the version manually.

Search for the current version in the project files and replace the relevant instances. Here is a list of files that you should update:

After pushing these changes, create a release on GitHub.

PyPI

Prerequisites

pip install build twine tbump

Create a Python Package

Create a Python source package (.tar.gz) and the binary package (.whl) in the dist/ directory using:

python -m build

python setup.py sdist bdist_wheel is deprecated and will not work for this package.

Then, upload the package to PyPI using:

twine upload dist/*

We upload to PyPI with the organizational user runai

Conda

The Conda package is managed using its feedstock.

After publishing to PyPI, update the version and sha256 fields in the recipe meta.yaml file.

A few minutes after pushing these changes, you should be able to see that the Conda package version was updated.

You can get the SHA256 hash from PyPI