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-depsfrom 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_databeforenetCDF4and 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.