Skip to content

JupyterLab environment setup

Overview

This guide explains how to configure your backend environment, load necessary system modules, and manage your Python virtual environments before launching your session.

1. Loading System Modules

If your workflow requires specific system-level libraries (e.g., compilers, CUDA toolkits, or specialized software), you can request them before JupyterLab starts.

  • How to use: Enter the exact module names in the [Insert Name of Module Field] field.
  • Format: Separate multiple modules with a space.
  • Example: gcc/11.2 cuda/11.8 proj/9.0.1

Note: These modules are loaded before any Python environments are activated, ensuring your environment variables and paths are set up correctly.

2. Python Environments

If you are using a Python kernel, you can tailor your package environment using the "Configure Python Environment?" checkbox. Checking this box reveals two ways to set up Python: using a curated LXP preset or bringing your own virtual environment.

A. Preset Environments

We provide several pre-configured environments optimized for specific research workflows. If you select one of these, you do not need to install common packages yourself.

  • None: Launches the default system Python.
  • Geospatial Analytics: Includes core spatial libraries: geopandas, rasterio, gdal.
  • GeoAI / Deep Learning: Tailored for spatial machine learning: terratorch.
  • PyTorch: torch, torchvision, matplotlib.
  • SCynergy 2026 - GeoAI: The official environment for the SCynergy 2026 - GeoAI session.

B. Custom User Virtual Environments (venv)

If you need absolute control over your packages, you can specify your own virtual environment.

  • How it works: When you enter an account name, the form will automatically suggest a standard path: /project/home/<Account_Name>/venvs/<Your_Venv_Name>. You can edit the <Your_Venv_Name> placeholder.
  • Auto-Creation: If the folder does not exist, our startup script will automatically run python -m venv to create and initialize it for you.
  • Reusability: This environment is persistent! You can reuse this exact same path in SSH sessions or HPC batch scripts.
  • Installing Packages: Once your JupyterLab session launches, open a Terminal inside Jupyter and run pip install <package_name> to add software to this environment.

3. Troubleshooting & Best Practices

  • Wrong Kernel Selected: If you intend to use R or Julia, do not check the Python configuration box.
  • Missing Packages: If you are using a custom venv and a package is missing, remember that you must install it yourself via pip the first time you use the environment.
  • Path Errors: Double-check your account name and custom venv path for typos. If the system cannot read/write to the directory you specify, the job will fail to start.