Skip to content

Install packages#

A runtime is a new container each time it starts, so what you install must land on the runtime's drive to still be there next time. This page shows where each way of installing puts packages, and which ones survive a restart.

You install With Kept on the drive?
Python packages, from a notebook %pip install, !pip install Yes: /content/.hesperus/python
Python packages, in an environment pip install --user Yes: ~/.local in your home on the drive
Python packages, at creation Setup → pip packages (--pip, setup.pip) Yes, installed once (again when the setup changes)
System packages (apt, dnf, apk) Setup → System packages (--apt, setup.apt) The downloads are cached on the drive; the packages are installed again at each start
Anything else Setup → Script (--setup-script, setup.script) What it writes under /content is
Anything, by hand as root apt-get install, pip install without --user No: gone at the next start

Before you begin#

In a notebook#

Install from a cell, as in Jupyter or Colab, and import in the next cell. No kernel restart is needed:

%pip install --quiet tabulate

from tabulate import tabulate
print(tabulate([["gpu", 1]], headers=["resource", "count"]))

!pip install tabulate works the same way. Packages go to the notebook's drive, under /content/.hesperus/python, not into the container: the next runtime of a notebook on that drive, on the same machine, has them already. A drive kept on each machine has one copy per machine, so a runtime on another machine sees that machine's copy.

Scripts that packages install (their bin) are on the kernel's PATH, and a package you upgrade with pip takes precedence over the image's own copy. In an image of your own whose Python runs in a virtual environment that ignores the user site, pip installs into the environment itself instead: the package works until the runtime stops, and is not kept.

A terminal opened over SSH in a notebook's runtime installs to the same place: pip install there lands on the drive too.

In an environment#

In an environment you log in with your home on its drive, /content/home/<user>. Install Python packages for your user, so they land in ~/.local on the drive. In the environment (astra ssh dev):

$ pip install --user einops==0.8.1
$ python -c "import einops; print(einops.__version__)"
0.8.1

Commands installed this way are in ~/.local/bin. Add it to your PATH once, in your home's .bashrc (also on the drive):

$ echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc

pip install without --user, as root, installs into the container's own Python: it works until the environment stops, then it is gone. A virtual environment made in your home (python -m venv ~/venvs/train) stays, with everything installed into it.

Once, at creation: the setup#

A runtime's setup installs what you list before Jupyter or the SSH server starts, so the runtime is ready when you connect:

  • pip packages: requirements such as transformers==5.18.0 or git+https://…, installed with pip install --user onto the drive (a notebook's /content/.hesperus/python, an environment's ~/.local). At most 64, each at most 256 characters; options (-r, --index-url) are refused.
  • System packages: packages of the image's package manager (apt, dnf or apk), such as ffmpeg libsndfile1 or nvtop=3.1.0-2. At most 64. They live in the container, so they are installed at every start, from a package cache on the drive: only the first start downloads them. The container must run as root and the image must have a package manager.
  • Script: a shell script run with sh, as root, in /content. At most 16 KiB.
  • Basic tools: git, curl, htop, tmux, and nvtop with GPUs, installed in the background when the image lacks them. On by default.

The pip packages and the script run once, and again when the setup (or the image) changes. A failure is logged, never fatal: the runtime starts, and the setup is tried again at the next start. A preset may add its own packages first: Hugging Face installs transformers==5.18.0, peft==0.21.2, datasets==5.0.1, accelerate==1.15.0 and bitsandbytes==0.50.2; CUDA dev adds build-essential, cmake, python3, python3-pip and python3-venv.

In New notebook, Change runtime…, Runtime settings or New environment, open Setup (packages and a script installed once at creation (again when changed), kept on the drive): pip packages (one per line), System packages, Script, and Basic tools.

For an environment (--pip and --apt are repeatable; --no-tools leaves the image as it is). The system packages are installed before the script runs, so the script can use git:

$ cat > setup.sh <<'EOF'
mkdir -p /content/projects
git clone --depth 1 https://github.com/karpathy/nanoGPT /content/projects/nanoGPT || true
EOF
$ astra env create dev --preset pytorch --gpus 1 --machine gpu-01 \
    --pip einops==0.8.1 --pip tensorboard==2.21.0 --apt git --apt ffmpeg --setup-script setup.sh
dev is pending: `astra ssh dev` connects once it is ready (and waits for it)

astra has no notebook commands: a notebook's setup is set in the console or the API.

spec.setup on a runtime (POST $API/notebook-runtimes), or spec.runtime_defaults.setup on a notebook:

{"setup": {"pip": ["einops==0.8.1"], "apt": ["ffmpeg"], "script": "mkdir -p /content/projects\n", "tools": true}}

Read the setup's log#

The setup writes to the runtime's output and to /content/.hesperus/env/<runtime>/setup.log on its drive. A runtime's run is <runtime>-<n> (n counts its starts) and its worker <runtime>-<n>-0:

$ astra ssh dev -- tail -n 20 /content/.hesperus/env/dev/setup.log
$ astra astraeus logs dev-1-0

In a notebook's editor, the runtime's menu has Its worker (logs). Lines from the setup start with hesperus-env:, such as setup: done (it runs again only when it changes) or setup: failed (see …); it is tried again at the next start. A basic tool the image's package manager does not have is noted and not tried again.