Installation

In Google Colab

Put this in the first cell of every notebook:

%pip install -q --upgrade colabutilscs4337
import colabutilscs4337 as cu
cu.env.check()

The first line cannot break your runtime. PyTorch, torchvision, fastai, NumPy, and Matplotlib are already installed in Colab, built for its GPU; this package uses those copies and never lists them as dependencies, so pip cannot replace them.

It does install the tools Colab lacks:

Package

Used by

torchinfo

summary()

netron

netron()

onnx,

netron() and

onnxscript

export_for_netron() (ONNX export)

CI installs the package inside Google’s Colab runtime image and fails if any preinstalled package changes. Their versions are capped below the next release, so a future onnx cannot pull in a newer NumPy or protobuf.

Optional extras, added with cu.install(...):

Extra

Installs

Needed for

cam

grad-cam

Grad-CAM++, Score-CAM, and other gradcam() methods

all

cam (and the tools above)

fastai

fastai

only if your runtime lacks fastai

If you call a function whose tool is missing, the error message tells you which cu.install(...) to run.

Why cu.install() instead of pip install?

pip happily upgrades or downgrades packages that are already installed when a new package asks for it. In Colab that can replace the GPU build of PyTorch and cost you a runtime restart (or a broken runtime). colabutilscs4337.install() prevents that:

  1. It records every installed package and version.

  2. It asks the installer, in a dry run, what it would do with all of those versions pinned.

  3. It installs only if nothing already installed changes; otherwise it stops and explains what would have changed.

cu.install("cam", dry=True)        # preview: "[dry run, uv] Added: grad-cam 1.5.7, ttach 0.0.3"
cu.install("cam")                  # install
cu.install("torchmetrics")         # any other package works too
cu.install("torchmetrics", upgrade=True)   # newer version; its dependencies stay as they are
cu.install("numpy==2.3.0")         # refused: would change Colab's numpy
cu.install("numpy==2.3.0", allow_changes=True)   # only if you really mean it

Fast installs with uv. Colab ships uv, a much faster installer, and cu.install uses it automatically (backend="auto"). Without uv it uses pip; if uv fails for any reason other than an impossible request, it retries with pip. Force one with backend="uv" or backend="pip".

Note

If you call uv yourself, avoid uv pip install --upgrade: unlike pip, it upgrades every dependency (Colab’s numpy, protobuf, …). Use uv pip install --system --upgrade-package NAME NAME instead, or simply cu.install(NAME, upgrade=True).

Plain pip works too, with the same protection, by pinning what is installed:

pip list --format=freeze | grep -viE '^(colabutilscs4337|torchinfo|netron|onnx|onnxscript|onnx-ir|grad-cam|ttach)==' > /tmp/c.txt
pip install -c /tmp/c.txt --upgrade "colabutilscs4337[all]"

Upgrading

Run the first cell again. If the upgrade replaced something you had already imported, cu.install prints a reminder; use Runtime > Restart session and run the notebook from the top.

Outside Colab

Everything also works in local Jupyter, VS Code, or plain Python (Python 3.12+). Install PyTorch yourself first, then pip install "colabutilscs4337[all]". Google Drive is replaced by a local ./drive/MyDrive folder.