aii-colab - SKILL.md Agent Skill

name: aii_colab description: Google Colab runtime constraints for generating Jupyter notebooks. Covers pre-installed packages, install patterns, and pitfalls. Read before creating any notebook meant to run on Colab.

Colab Runtime (as of 2026-02)

Python: 3.12.12
OS: Linux 6.6.105+ x86_64, glibc 2.35

Critical Rule: Do NOT pip install pre-installed packages ON COLAB

Colab's core scientific packages have compiled C extensions linked against each other at specific ABI versions. Installing ANY different version (even a minor bump) partially overwrites files while the loaded .so extensions stay in memory, causing:

ValueError: numpy.dtype size changed (numpy 1.x vs 2.x ABI)
ImportError: cannot import name '_center' (numpy 2.0 vs 2.2 ABI)
Silent corruption of scipy/sklearn/pandas internals

On Colab: do NOT install these packages. Use Colab's versions. Locally: MUST install these packages at Colab's exact versions to match the Colab environment.

Pre-installed Core Packages

These are pre-installed on Colab. On Colab: skip them. Locally: install at these exact versions.

numpy==2.0.2
pandas==2.2.2
scikit-learn==1.6.1
scipy==1.16.3
matplotlib==3.10.0
seaborn==0.13.2
torch==2.9.0+cpu
tensorflow==2.19.0
xgboost==3.1.3
lightgbm==4.6.0
networkx==3.6.1
Pillow==11.3.0
opencv-python==4.13.0.92
sympy==1.14.0
statsmodels==0.14.6
bokeh==3.7.3
plotly==5.24.1
nltk==3.9.1
spacy==3.8.11
transformers==5.0.0
datasets==4.0.0
tokenizers==0.22.2
huggingface_hub==1.4.0
openai==2.17.0
requests==2.32.4
beautifulsoup4==4.13.5
lxml==6.0.2
pydantic==2.12.3
tqdm==4.67.3
rich==13.9.4
tabulate==0.9.0
PyYAML==6.0.3
jsonschema==4.26.0
h5py==3.15.1
Cython==3.0.12
numba==0.60.0
dask==2025.12.0
polars==1.31.0
pyarrow==18.1.0

Install Cell Pattern

The install cell must work on BOTH Colab and local Jupyter. Use this conditional pattern:

import subprocess, sys
def _pip(*a): subprocess.check_call([sys.executable, '-m', 'pip', 'install', '-q', *a])

# Packages NOT pre-installed on Colab (always install everywhere)
_pip('some-rare-pkg==1.2.3')

# Core packages (pre-installed on Colab, install locally to match Colab env)
if 'google.colab' not in sys.modules:
    _pip('numpy==2.0.2', 'pandas==2.2.2', 'scikit-learn==1.6.1', 'scipy==1.16.3', 'matplotlib==3.10.0')

How this works:

On Colab: google.colab is in sys.modules → skips core packages (uses Colab's pre-installed ones) → only installs non-Colab packages
Locally: google.colab is NOT in sys.modules → installs core packages at Colab's exact versions → local .venv matches Colab's environment as closely as possible

Rules:

CRITICAL: On Colab, pip installing ANY version of numpy/pandas/sklearn/scipy/matplotlib (even the same version) CORRUPTS the pre-loaded C extensions. These MUST be behind the google.colab guard.
Check the pre-installed package list above. If a package is on that list, put it in the google.colab guard block. If not, install it unconditionally.
For the local (non-Colab) install, use the EXACT versions from the list above so the local environment matches Colab.
Do NOT use --force-reinstall — corrupts Colab system packages.
Do NOT use %pip or !pip — use the _pip() helper for proper conditional control.
%%capture hides install noise — only add AFTER testing is done.
If a package requires a newer numpy/scipy than Colab has, that package is INCOMPATIBLE with Colab — find an older version or alternative.

Example

Code imports: numpy, pandas, sklearn, matplotlib, imodels, dit, rich

import subprocess, sys
def _pip(*a): subprocess.check_call([sys.executable, '-m', 'pip', 'install', '-q', *a])

# imodels, dit — NOT on Colab, always install
_pip('imodels==2.0.4')
_pip('--no-deps', 'dit==1.5')

# numpy, pandas, sklearn, matplotlib, rich — pre-installed on Colab, install locally only
if 'google.colab' not in sys.modules:
    _pip('numpy==2.0.2', 'pandas==2.2.2', 'scikit-learn==1.6.1', 'matplotlib==3.10.0', 'rich==13.9.4')

Checking if a package is pre-installed

Before adding a package to the install cell, check:

Is it in the pre-installed list above?
If unsure, skip it — Colab has 500+ packages pre-installed. If the import works without installing, it's pre-installed.

NumPy 2.0 Compatibility for Non-Colab Packages

Colab has numpy 2.0.2. NumPy 2.0 removed several long-deprecated APIs that older packages still use. If a non-Colab package was written for numpy 1.x, it may crash at runtime with errors like:

AttributeError: np.alltrue was removed in the NumPy 2.0 release
AttributeError: np.sometrue was removed in the NumPy 2.0 release
AttributeError: np.product was removed in the NumPy 2.0 release

Fix: Add a compat shim in the imports cell (BEFORE importing the affected package):

import numpy as np
if not hasattr(np, "alltrue"): np.alltrue = np.all
if not hasattr(np, "sometrue"): np.sometrue = np.any
if not hasattr(np, "product"): np.product = np.prod

When to add this: After installing non-Colab packages, test-run the notebook. If you get AttributeError: np.X was removed, add the corresponding shim. Common offenders: dit, older scientific libraries that haven't been updated for numpy 2.0.

Colab-Specific Gotchas

No kernel restart after pip install — Unlike local Jupyter, Colab doesn't cleanly reload C extensions after pip install. Once numpy/scipy/sklearn are loaded, their C code stays in memory forever until full runtime reset.
%pip vs _pip() helper — In notebook install cells, use the _pip() helper (see pattern above) so you can wrap installs in Python if conditionals. %pip and !pip can't be used inside if/else blocks.
File system — /content/ is the working directory. Files persist within a session but are lost on runtime disconnect.
Memory — Free tier: ~12GB RAM. Pro: ~25-50GB. Monitor with !free -h.
Timeouts — Free tier disconnects after ~90 min idle, ~12 hours max session. Pro: longer.
%%capture — Suppresses all cell output including errors. Only use on install cells AFTER verifying they work. During development, leave install output visible.

Testing Notebooks Locally (Simulating Colab)

The goal: create a clean Python 3.12 .venv that mirrors Colab's environment, then run the notebook in it.

python3.12 -m venv .nb_env
.nb_env/bin/pip install -q pip jupyter ipykernel
.nb_env/bin/jupyter nbconvert --to notebook --execute code_demo.ipynb --output code_demo.ipynb
rm -rf .nb_env

What happens when the notebook runs in this .venv:

The .venv starts empty (just jupyter + ipykernel)
The install cell runs → google.colab is NOT in sys.modules
Non-Colab packages get installed unconditionally
Core packages (numpy, pandas, etc.) get installed at Colab's exact versions via the google.colab guard
Result: the .venv now has the same packages as Colab + the extra non-Colab packages = as close to Colab as possible

This ensures the notebook works from scratch with an environment matching Colab. If a cell fails, fix the notebook and re-run.