Packages in your runtime

Every runtime starts from its Environment image, which already contains the packages you listed when you built it. Anything you install on top of that with pip inside a running session lands in a durable, per-Environment user site on your workspace, so it is still importable the next time you start a runtime on the same Environment. Nothing to configure: a plain

!pip install rich

in a cell, or pip install rich in the terminal or over SSH, is enough. Stop the runtime, start a new one on the same Environment, and import rich works.

What persists, and what does not

Where it livesSurvives a stop?Notes
Files under ~/workspaceYesYour workspace filesystem.
pip install <pkg> (kernel, terminal, SSH)Yes, on the same EnvironmentInstalled into ~/workspace/.ns-cache/pyuser/<environment>/py<X.Y>.
pip's download cache, Hugging Face hub cache (HF_HOME), XDG_CACHE_HOMEYesUnder ~/workspace/.ns-cache/, shared by every runtime of the workspace.
sudo pip install …NoRuns as root and installs into the image itself, which is discarded with the runtime. Drop the sudo.
apt-get install …, edits under /opt, /etc, /usrNoThe image is ephemeral. Put system packages in your Environment (System packages) so they are baked in.
~/.local, ~/.cache, /tmp, /scratchNoThe home directory and the local NVMe scratch disk are wiped with the runtime.

Persisted packages are keyed by the Environment and its Python X.Y, so a runtime on a different Environment, or on the same Environment rebuilt with a different Python line, starts clean. That is deliberate: wheels are bound to the interpreter ABI they were built for.

The .ns-cache directory is managed by the platform. It is hidden from the Files page and cannot be addressed through the Files or notebook APIs; you will see it on the runtime, and you can delete a stale user site from the terminal (rm -rf ~/workspace/.ns-cache/pyuser/<environment>) if you want a clean slate for that Environment.

Save them as an Environment

Persisted installs are a convenience, not a recipe. When you stop a runtime that has packages installed outside its image, Neural Studio offers to save them as an Environment (the same Save as Environment action as the notebook menu). Accepting runs pip freeze on the runtime and creates a new Environment whose build bakes those packages into the image, so every future runtime on any machine starts with them and your collaborators can launch the same thing. Do this once you know which packages you want to keep.

How it works (and the sharp edges)

The runtime exports PYTHONUSERBASE pointing at the per-Environment directory above and PIP_USER=1, so pip install behaves as pip install --user and Python's user site is on sys.path from the first import.

  • The user site shadows the image. If you pip install a package the image already ships, the new version wins for this Environment until you remove it from the user site. That is what makes upgrading a package stick; it also means a bad upgrade follows you to the next runtime. pip uninstall <pkg> removes the user-site copy and the image's copy is visible again.
  • Virtual environments. pip refuses --user inside a virtualenv. If you create one, either create it with python -m venv --system-site-packages .venv, or set PIP_USER=0 for that pip (PIP_USER=0 .venv/bin/pip install …). uv is unaffected; it ignores PIP_USER.
  • Escape hatch. PIP_USER=0 pip install <pkg> installs into the image for this session only, exactly as before. --target and --prefix installs also need PIP_USER=0.
  • Console scripts. Executables from user-site installs land in $PYTHONUSERBASE/bin. Terminal and SSH shells have it on PATH; from a notebook cell, run them as !python -m <module>.
  • First import can be slower. The user site lives on the workspace filesystem, so the first import of a large package after a fresh start reads it over the network once; later imports are served from the runtime's local cache.
  • Workspace quota. Everything under .ns-cache counts toward the workspace's storage quota like any other file.