colab-run

colab run [-s NAME] [--gpu GPU] [--tpu TPU] [--high-mem] [--keep] [--timeout SEC] [--env KEY=VALUE]... SCRIPT [ARGS...]

colab run is a subcommand of colab, not a separate binary. It is `colab new` plus `colab exec` plus `colab stop` in one invocation: allocate a VM, run a local `.py` file as `_main_` with a reconstructed `sys.argv`, then release the assignment unless --keep.The payload sets `sys.argv` to the script basename plus forwarded args, forces `_name = 'main_'`, applies --env, and filters the IPython "To exit: use 'exit'..." warning so `sys.exit` behaves like `python script.py`. Working directory on the VM is `/content`. Stdout, stderr, and display data stream back to the terminal. `SystemExit` is mapped to a CPython-style process exit code (`None`/0 → 0, an integer → that integer, anything else → 1); other kernel errors exit 1.A typical shebang is `#!/usr/bin/env -S colab run --gpu T4`. `chmod +x` and `./script.py` then rents a runtime, runs the file, and tears it down.

SCRIPT

Local Python file. Must exist before a VM is allocated. A leading `#!` shebang line is stripped before the body is sent to the kernel.

Extra arguments become `sys.argv[1:]` on the VM. Unknown options after the script path are forwarded, so `colab run train.py --epochs 3` works.

Name for the ephemeral session. Default is `run-` plus six hex characters. Useful with --keep so a later `colab exec -s` can attach.

GPU accelerator. Combined with --tpu, --tpu wins. With neither flag, the runtime is CPU.

TPU accelerator.

Request a high-RAM machine shape (Colab Pro or Pro+). Ignored for L4 and TPU.

Leave the session assigned after the script exits. Without this flag the VM is unassigned even if the script fails.

Kernel execution timeout in seconds. Default is 30.0.

Set `os.environ[KEY]` in the remote kernel. Repeatable. Also accepted after the script path (`colab run script.py --env KEY=VALUE`).

Default --timeout is 30 seconds; a training script that needs minutes must pass a larger value or it is killed while the VM is still billed until teardown.An unrecognized --gpu string is mapped to A100, not rejected. --tpu and --gpu together use the TPU. --high-mem is ignored for accelerators that have only one shape.The script is validated locally first so a bad path does not allocate compute. Allocation can still fail with 412 (too many sessions or a capacity limit) or 400 (no quota for that accelerator). Artifacts stay on the VM; copy them with colab download and --keep, or write them to stdout.

Designed as a shebang-friendly one-shot runner in the Colab CLI (PyPI `google-colab-cli`) in 2026. --env and --high-mem arrived in 0.7.0 (3 September 2026). Google announced the CLI on 5 June 2026.

colab(1), colab-exec(1), python3(1), uv(1)

Source code · Documentation