Check your setup

Run the following commands in a terminal with your DEFAIR environment active. In JupyterLab, select the DEFAIR kernel and use the Python command-line check to inspect that kernel’s installation.

1. The command line tool

defair version

In a notebook, use its Python interpreter explicitly:

import sys
import subprocess

print(sys.executable)
subprocess.run([sys.executable, "-m", "defair", "version"], check=True)

Expected, after one log line, the version you installed:

defair <version>

2. The readers

defair readers

In a Jupyter notebook, run this complete Python cell to list the readers from the selected kernel’s DEFAIR installation:

import sys
import subprocess

subprocess.run([sys.executable, "-m", "defair", "readers"], check=True)

Expected: after one log line, a table with the columns Reader, Product and Collection ID, one row per product DEFAIR reads. It starts with the Metop readers:

2026-09-24 00:15:03 | INFO     | [098441b7] defair.cli.readers:readers_cmd:61 - Listing reader products
Reader                Product                                                                                            Collection ID
--------------------  -------------------------------------------------------------------------------------------------  ----------------------------
metop_amsul1          AMSU-A Level 1B - Metop - Global                                                                   EO:EUM:DAT:METOP:AMSUL1
metop_ascszf1b        ASCAT Level 1 Sigma0 Full Resolution - Metop - Global                                              EO:EUM:DAT:METOP:ASCSZF1B

3. Your object store

Configure the credentials for your S3 bucket as described in Prepare data access for DEFAIR. Run the following Python code from the folder containing your .env file, replacing s3://your-bucket/your-prefix/ with the bucket and prefix you want to list:

from dotenv import load_dotenv
from defair.plugin_manager import load_source

load_dotenv(override=True)
print(load_source("s3").list("s3://your-bucket/your-prefix/"))

Expected: a Python list of s3:// URIs, one per object or folder directly under the prefix:

['s3://your-bucket/your-prefix/2025', 's3://your-bucket/your-prefix/README.txt']

4. The optional packages

For the tutorial notebooks:

python -c "import cartopy, healpy, earthkit.data, ipykernel"

For the AI tutorial:

python -c "import torch, defair_ai_demo"

Expected: no output at all. An error names the missing package.

5. Writing into output

Every notebook writes under output/ next to itself. From the notebook folder:

from pathlib import Path

Path("output").mkdir(exist_ok=True)
Path("output/write-test.txt").write_text("ok")
print("ok")

Expected: ok, and a new file output/write-test.txt. Delete it afterwards.

When a check fails

  • Pip rejects typing-extensions metadata or cannot find flit_core. Upgrade pip before installing packages. Install the CPU PyTorch wheel with --no-deps from its CPU index, then install the AI package and the remaining dependencies from PyPI, using the two commands in the installation guide.

  • A process aborts during shutdown after loading HDF5 libraries. Import defair_data before netCDF4 and other HDF5-backed I/O libraries. This import order resolved the native-library shutdown failure reproduced during separate output checks. Restart the notebook kernel before retrying if those libraries are already loaded.

Symptom

Likely cause

Fix

defair: command not found

The DEFAIR environment is not active, or pip installed into another Python

Run source defair-env/bin/activate and try again. In a notebook, print sys.executable and pick the defair kernel

The defair kernel is missing from the kernel menu after your DEDL JupyterHub server restarted

A restart resets your home directory outside ~/user_data, including the kernel registration in ~/.local

In a terminal, run ~/user_data/envs/defair/bin/python -m ipykernel install --user --name defair --display-name "DEFAIR". The environment itself survives and needs no reinstall

PermissionError: Forbidden, 403 or AccessDenied on your own store

No keys were found, so DEFAIR sent unsigned requests and logged No S3 credentials found. Or the keys are wrong, expired, or not allowed on that bucket

Put AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY in .env in the notebook folder or above it, and load it with load_dotenv(override=True). If they are there, check them, and check that AWS_ENDPOINT_URL is the store that issued them

NoSuchBucket

Bucket name typo, or the endpoint points at another store

Check the bucket name and AWS_ENDPOINT_URL

Could not connect to the endpoint URL

AWS_ENDPOINT_URL is wrong or unreachable

Check the URL, the network and any proxy

FileNotFoundError: File not found: <path> on a local path

The path is wrong, or it is relative and Python runs from another folder

Check the path, and print the working directory with os.getcwd(). A notebook runs from its own folder, so a relative path starts there

FileNotFoundError: S3 prefix not found

The prefix does not exist in that bucket. At the bucket root, the keys are missing or not allowed to list it

List the bucket root, s3://your-bucket/, and walk down from there. If the root gives the same error, fix the keys as for Forbidden

Empty list []

The prefix exists but holds nothing at that level

Same as above, the data may sit one level deeper

ImportError: libexpat.so.1: cannot open shared object file

A minimal Linux image without the expat library, which rasterio loads

apt-get update && apt-get install -y libexpat1

ModuleNotFoundError: No module named 'cartopy' (or healpy, earthkit, ipykernel)

The notebooks extra is not installed

Repeat the pinned installation with the notebooks extra in Install DEFAIR locally.

ModuleNotFoundError: No module named 'satpy'

Python older than 3.11, where satpy is skipped

Use Python 3.11 or newer for tutorial 10

ModuleNotFoundError: No module named 'torch' or 'defair_ai_demo'

The AI tutorial package is not installed

Follow the CPU PyTorch and AI-package steps in Install DEFAIR locally.

The kernel dies or restarts during a tutorial

Out of memory. Peaks reach 3.8 GB with Dask on one core and 4.8 GB on sixteen (tutorial 06), and grow with the number of cores Dask uses

Use a machine or server profile with more memory, or run Dask on fewer cores: dask.config.set(num_workers=1) in the first cell, or a smaller threads_per_worker in the get_dask_client(...) cell of tutorial 06

PermissionError on output/

The notebook folder is read-only

Move the notebooks to a folder you can write to

What to do next

For the pinned package versions and installation fixes, use Install DEFAIR locally or Run DEFAIR on the DEDL JupyterHub.

Continue with Read your first product to read an MSG SEVIRI image, select a channel, crop it and save a Zarr dataset. Then follow Run your first workflow to run the same processing from a YAML file.