The UChicago BinderHub
BinderHub is the recommended way to run Jupyter notebooks at the UChicago Analysis Facility. It launches a JupyterLab server on the AF from either a curated, pre-built image or any Git repository you point it at.
Replacing the AF Portal JupyterLab
The JupyterLab service in the AF Portal (Services → JupyterLab) is no longer available. Please move your work to BinderHub. See The UChicago JupyterLab for the retired service.
How to launch a notebook
- Go to https://binderhub.af.uchicago.edu/ (or choose Services → BinderHub in the AF Portal) and log in with your AF account.
- Optionally open Advanced setting - sites and resource customizations to request GPUs or change the CPU and memory for your notebook (see Resources below).
- Under Curated Repositories, choose an image from the Select a curated repo... dropdown. BinderHub fills in the repository and Git ref for you and starts launching.
- Wait for the progress bar to finish. You can follow along in Build Logs. Once the server is ready, JupyterLab opens in your browser.
Your running servers are listed on the JupyterHub home page at https://jupyterhub.af.uchicago.edu/hub/home, where you can reopen or stop them. The JupyterHub Home button in the advanced settings panel also takes you there.
Curated repositories
Curated repositories are pre-built images maintained by the facility team. They start quickly because they don't need to be built, so we expect most users to pick one of these:
| Curated repo | Source | Description |
|---|---|---|
AB-STABLE |
usatlas/analysisbase-dask-uc (binderhub-prod) |
Based on AnalysisBase |
AB-DEV |
usatlas/analysisbase-dask-uc (binderhub-dev) |
AnalysisBase with cutting edge uproot, dask, awkward, etc. |
ml-platform:latest |
maniaclab/ml_platform (main) |
Latest ml_platform machine learning image (recommended) |
ml-platform-cpu:latest |
maniaclab/ml_platform-cpu-binder (main) |
Latest CPU-only ml_platform image |
ml-platform-gpu:latest |
maniaclab/ml_platform-gpu-binder (main) |
Latest GPU ml_platform image |
ml-platform-cpu:2026.11.4 |
maniaclab/ml_platform-cpu-binder (v2026.11.4) |
Pinned CPU-only ml_platform release |
ml-platform-gpu:2026.11.4 |
maniaclab/ml_platform-gpu-binder (v2026.11.4) |
Pinned GPU ml_platform release |
These are the same images previously offered by the AF Portal JupyterLab. See
Docker Images for what each one contains and how to install
additional packages with pixi.
Docker Images
ml_platform
The primary image available is ml_platform, a comprehensive machine learning
platform that includes:
- Python 3.12 with ML frameworks (TensorFlow, Keras, scikit-learn)
- ROOT 6.32+ for HEP analysis
- JupyterLab with extensions (RISE, Git integration, ipywidgets)
- HEP tools (uproot, atlasify, rucio-jupyterlab)
- NVIDIA GPU support (CUDA 13.0)
- Data science libraries (NumPy, Pandas, SciPy, PyArrow, HDF5)
Available tags:
ml-platform-cpu:latest- Latest stable version (recommended)ml-platform-cpu:<release>- Pinned release, e.g.ml-platform-cpu:2026.11.4ml-platform-gpu:latest- Latest stable version (recommended)ml-platform-gpu:<release>- Pinned release, e.g.ml-platform-gpu:2026.11.4
For the complete list of packages, version information, and detailed documentation, see the ml_platform repository.
Installing Additional Packages
You can install additional packages directly from your notebook with
pixi. The ml_platform image organizes
packages under features. ML-related packages live in the mlbase feature
(-f mlbase / --feature mlbase), which is shared by the ml and mlcpu
environments. If you are not using a GPU-node, you can use the mlcpu
environment which has the same set of packages without the cuda system
requirement.
Example: installing the GPU-version of pytorch along with torchvision
and xgboost available on conda-forge, you
can run the following inside the notebook
Then restart the kernel. The ! prefix runs the command directly from a
notebook cell; you can also open a terminal in JupyterLab and run the same
commands without the !.
For more advanced pixi usage, including custom environments and multi-environment support, see the pixi section below.
AnalysisBase Images
- AB-stable - Based on AnalysisBase
- AB-dev - Based on AnalysisBase but with cutting edge uproot, dask, awkward arrays, etc.
Other Images
Additional images may be available in the Select a curated repo... dropdown. Contact the facility team if you need a specific software environment not provided by these images.
Resources (advanced setting)
Click show next to Advanced setting - sites and resource customizations to customize your notebook's resources before launching:
- Sites: choose which cluster your notebook runs on. The default is UC AF; you can also choose ssl or nrp (the National Research Platform), for example if the GPU you need is not available on the UC AF.
- GPU Model - name (avail/total): the GPU model to request. Each entry shows
how many GPUs of that model are free out of the total, for example
NVIDIA-GeForce-RTX-2080-Ti (21/24). Models with none free are greyed out. Choose Any (auto-assign GPU) if you don't need a specific model. - GPU count (the number box next to the GPU model): how many GPUs to
request. Leave it at
0for a CPU-only notebook. - QoS — Guaranteed: check this box to reserve a fixed amount of CPU and memory for your notebook. This enables the CPU and Memory fields.
- CPU: the number of CPU cores to reserve (1 to 32).
- Memory: the amount of memory to reserve, in GB.
The GPU list and availability depend on the selected site, and models like
NVIDIA-A100-SXM4-40GB-MIG-1g.5gb are slices (MIG instances) of a larger GPU.
Please request only the resources you need, especially GPUs, which are shared by
everyone on the facility.
Launching your own repository
You can also build and launch any Git repository, for example a fork of one of the curated repos with your own dependencies:
- In Build and launch a repository, pick the repository type (GitHub, GitLab, Git repository, Zenodo DOI, ...) and enter the repository name or URL.
- Set the Git ref (branch, tag, or commit). It defaults to
HEAD. - Optionally give a File to open once JupyterLab starts.
- Click launch.
BinderHub builds a Docker image from the dependency files in your repository
(such as requirements.txt or environment.yml), so the first launch of a new
commit takes longer. See the
Binder documentation
for how to prepare a repository. The form also shows a reusable launch URL, like
https://binderhub.af.uchicago.edu/v2/gh/<org>/<repo>/<ref>, and a badge you
can add to your README.
Your files and storage
Your notebook runs as your AF user and starts in your AF home directory,
/home/<username>. Your /data directory and /cvmfs are also available.
Files saved there persist after your notebook stops; anything saved elsewhere in
the container is lost.
Idle notebooks are stopped automatically after 24 hours.
pixi
pixi is a modern package manager that
provides powerful environment management capabilities. While the ml_platform
image includes basic pixi support for adding packages, pixi can also create
fully isolated custom environments for different projects using
pixi-kernel.
Creating Custom Environments with pixi-kernel
For complex setups where you need isolated environments for different projects, you can use pixi-kernel to create and manage multiple custom kernels in JupyterLab.
Understanding pixi features and environments:
- A feature is a named collection of packages (e.g.,
data-science,nlp) - An environment can combine multiple features together
- Multiple environments can point to the same features in different combinations
- This gives you full control over your dependencies, even more than conda/pip
Learn more about pixi's multi-environment support in the official documentation.
Creating a custom environment from a conda YAML file:
If you have an existing conda environment.yml file, you can import it into
pixi and register it as a kernel:
-
Create your environment file (e.g.,
my_env.yml): -
Import the environment into pixi as a new feature:
-
Register the kernel with pixi-kernel:
Using your custom kernel in JupyterLab:
- When you first start JupyterLab, you'll be using the default
ipykernel - To switch to your custom environment:
- Click the kernel selector in the top-right corner
- Select the
pixikernel (this enables multi-environment support) - Click the property inspector (gear icon) on the right sidebar
- Select your custom environment (e.g.,
my-custom-env) - Save the notebook
- Restart the kernel
Your notebook will now use the selected pixi environment. Each notebook can use a different environment, and the selection is saved with the notebook.
Additional resources:
- Pixi import tutorial - various ways to import existing environments
- Pixi multi-environment guide - comprehensive tutorial on managing multiple environments
- pixi-kernel GitHub - kernel integration documentation
Creating Features from Scratch
Instead of importing from a conda YAML file, you can create features directly with pixi commands. This is useful when you want to build an environment incrementally or don't have an existing environment file.
Example: Creating a custom analysis feature:
# Create a new feature with core packages, including pixi-kernel
!pixi add -f analysis numpy pandas matplotlib scipy uproot awkward hist pixi-kernel
# Specify Python version if needed
!pixi add -f analysis "python>=3.11"
Creating a feature does not automatically create a matching environment or kernel — you must register one explicitly, combining as many features as you need:
You can also combine packages from different channels:
# Add packages from specific channels
pixi add -f ml-custom -c pytorch -c conda-forge pytorch torchvision
pixi add -f ml-custom scikit-learn xgboost
pixi add -f ml-custom pixi-kernel
pixi project environment add ml-custom -f ml-custom
pixi lock
Once created, restart the kernel so the new environment (e.g. debug) shows up
in the property inspector, then follow the same steps described in "Using your
custom kernel in JupyterLab" above to select it, save the notebook, and restart
the kernel again. The first time you switch to a newly created environment, pixi
has to build it from scratch, which can hang for up to a minute while it
installs all the packages — this is expected and only happens once.
Managing Environments
As you work with pixi, you'll need to manage your features and environments. Here are essential commands for day-to-day operations:
View available features and environments:
# Show all features, environments, and installed packages
pixi info
# List packages in a specific environment
pixi list -e my-env
Update packages:
# Update specific packages in a feature
pixi update -f mlbase pytorch torchvision
# Update all packages in a feature
pixi update -f mlbase
# Update all packages in all environments
pixi update
Remove packages:
# Remove a package from a feature
pixi remove -f analysis matplotlib
# Remove multiple packages
pixi remove -f analysis matplotlib seaborn plotly
Clean up disk space:
# Remove unused packages and caches
pixi clean
# Remove a specific environment's cache
pixi clean cache -e my-env
Reinstall an environment:
If an environment becomes corrupted or you want to start fresh:
Best Practices
Choose the right approach for your needs to keep your environments manageable and maintainable:
When to use the simple approach (add to the mlbase feature):
- You need just a few additional packages
- Packages are compatible with the existing
mlormlcpuenvironment - You're doing exploratory work or quick prototyping
- You don't need strict version control
When to create a custom environment:
- You need specific package versions that conflict with
mlormlcpu - You're working on a long-term project with specific dependencies
- You want to isolate different projects from each other
- You're collaborating and need reproducible environments
- You need different Python versions for different projects
Preserving environments across sessions:
JupyterLab instances run in ephemeral Docker containers. When your notebook server stops, custom pixi environments are not preserved. To recreate your environments in a new session:
- Save your environment YAML files (e.g.,
my_env.yml) in your persistent home directory or a git repository - When starting a new JupyterLab session, re-run the
pixi importandpixi addcommands to recreate your environments - Consider creating a setup script in your home directory that recreates all your environments automatically
Environment naming:
Use descriptive names that indicate the purpose:
- ✅
deep-learning-gpu,hep-analysis,data-viz - ❌
my-env,test,new-env
Troubleshooting
Common issues and solutions when working with pixi environments:
Problem: Kernel not appearing in JupyterLab
After creating a feature and adding pixi-kernel, the kernel doesn't show up in
the property inspector.
Solution:
- Verify
pixi-kernelwas added to the feature:pixi list -e my-env | grep pixi-kernel - Reinstall the environment:
pixi install -e my-env - Restart JupyterLab completely (stop and start the notebook server)
- Make sure you've switched to the
pixikernel (notipykernel)
Problem: Package conflicts during installation
You get conflicts when trying to add packages or import an environment.
Solution:
# Try updating the lock file
pixi update -f my-feature
# If conflicts persist, you may need to adjust version constraints
# Edit pixi.toml to relax version requirements, or
# Create a separate feature for conflicting packages
Problem: Environment not appearing in property inspector
You created an environment but it doesn't show up when you click the gear icon.
Solution:
The property inspector only shows environments that have pixi-kernel
installed:
# Add pixi-kernel to your feature
pixi add -f my-feature pixi-kernel
pixi install -e my-feature
# Restart the kernel in JupyterLab
Problem: "No module named..." after switching environments
You selected an environment in the property inspector but imports still fail.
Solution:
- Save the notebook after selecting the environment
- Restart the kernel (Kernel → Restart Kernel)
- Verify the correct environment is active by checking the kernel name
- Confirm the package is installed:
pixi list -e my-env | grep package-name
Problem: Running out of disk space
Multiple environments are consuming too much storage.
Solution:
# Clean up cached packages
pixi clean
# Check disk usage
du -sh ~/.pixi
# Remove unused features by editing pixi.toml and running
pixi install
# Consider using the shared mlbase feature for common packages
Problem: Import is slow or hangs
pixi import or pixi install seems to hang or takes a very long time.
Solution:
- Large environments with many dependencies can take several minutes
- Check your internet connection (pixi downloads packages)
- If truly stuck, interrupt (Ctrl+C) and try again
- Consider breaking large environments into smaller, focused features
Problem: Wrong Python version
Your environment is using a different Python version than expected.
Solution:
Explicitly specify the Python version when creating the feature:
# For a specific version
pixi add -f my-feature "python=3.11"
# For a minimum version
pixi add -f my-feature "python>=3.11"
Getting more help:
If you encounter issues not covered here:
- Check the pixi documentation
- Run
pixi --helporpixi <command> --helpfor command-specific help - See the Getting Help section for facility support
Dask clusters
The AB-STABLE and AB-DEV images come set up for the AF's Dask Gateway, so
you can start a Dask cluster from the Dask sidebar or from code. See
Dask Gateway.
Connecting an MCP client to your notebook
Once your JupyterLab is running you can attach an MCP (Model Context Protocol) client — Claude Code, Cursor, Continue, or any mcp-remote-compatible client — so the assistant can list, read, and execute cells in your live notebook session.
Security & lifetime model (read this first)
The MCP server runs inside your singleuser pod — there is no shared service to log into. That has two practical consequences:
| Surface | Endpoint | Token | Token lifetime | Endpoint lifetime |
|---|---|---|---|---|
https://jupyterhub.af.uchicago.edu (BinderHub-launched) |
/user/<name>/proxy/3001/mcp |
JupyterHub API token, scope access:servers (or the tighter access:servers!user=<name>) |
Durable — mint once at /hub/token, reuse across spawns |
Only while your server is running; if culled, the endpoint 404s until you spawn again, then the same token reconnects |
This design is intentional: the credential is scoped to your identity, the endpoint is scoped to one running compute. There is no independent, always-on MCP service — that would break per-user isolation.
From https://jupyterhub.af.uchicago.edu (BinderHub-launched notebooks)
Step 1 — mint an API token. Visit
https://jupyterhub.af.uchicago.edu/hub/token,
create a token, and request the access:servers scope. If you want to
restrict the token to your own server only, use
access:servers!user=<your-username> instead — same connectivity, tighter
blast radius if the token leaks. Save the token in your password manager; you
will not see it again.
Step 2 — configure your client.
For Claude Code:
claude mcp add jupyter --transport http \
https://jupyterhub.af.uchicago.edu/user/<your-username>/proxy/3001/mcp \
--header "Authorization: Bearer <your-api-token>"
For Claude app, Cursor, Continue, or any client configured via
claude_desktop_config.json / mcp_servers.json:
{
"mcpServers": {
"jupyter": {
"command": "npx",
"args": [
"-y",
"mcp-remote",
"https://jupyterhub.af.uchicago.edu/user/<your-username>/proxy/3001/mcp",
"--header",
"Authorization:${JUPYTERHUB_AUTH_HEADER}"
],
"env": {
"JUPYTERHUB_AUTH_HEADER": "Bearer <your-api-token>"
}
}
}
}
Step 3 — make sure your server is running. If MCP returns 404, your pod has been culled. Open your JupyterHub home page to respawn; the same token will reconnect immediately.
What the MCP server can do
See the upstream Jupyter MCP Server documentation for the current tool surface (cell listing, cell read / insert / execute, kernel control, document state).
Getting help
For software additions, upgrades, or questions about the JupyterLab environment:
- See our Getting Help page for support options
- Contact the UChicago facility team
- Open an issue for ml_platform image problems