Environments
An environment is a container image: a base, Python 3.12, and the packages you listed, built once and reused by every runtime you launch on it. Every runtime boots from one. You pick it in the runtime bar under Environment, and the Environments page is where you build, edit and share them.
Templates
The platform ships pinned, ready-to-launch templates. You do not have to build anything to start.
| Template | Base | What is in it |
|---|---|---|
| Blank | Slim (CPU) | Python and JupyterLab, nothing else. |
| Data Science | Slim (CPU) | NumPy, pandas, scikit-learn, Matplotlib. |
| PyTorch + CUDA | CUDA (GPU) | PyTorch and torchvision. |
| HuggingFace NLP | CUDA (GPU) | Transformers, Datasets and Accelerate. |
| Computer Vision | CUDA (GPU) | PyTorch, torchvision, OpenCV and Pillow. |
| JAX + Flax | CUDA (GPU) | JAX with Flax and Optax. |
| Reinforcement Learning | CUDA (GPU) | Gymnasium and Stable-Baselines3 on PyTorch. |
Templates are fully pinned, so a launch today and a launch next month run the same versions. Templates cannot be edited in place: Duplicate one to get your own copy to change.
Building your own
New Environment on the Environments page offers three starts:
- Templates: start from a template's recipe.
- Upload requirements.txt: import the packages from a file you have.
- Manual: an empty recipe.
The builder then shows:
- Name, Description and Tags.
- Base Image: Slim (CPU) for CPU runtimes, or CUDA (GPU) with a CUDA version and a CUDA flavor. Every CUDA environment currently builds on the platform's CUDA base (CUDA 13.0, which needs an NVIDIA driver of 580 or newer); the version you type is recorded with the environment.
- Python version: 3.12 is the only line offered today.
- Python packages, one per row, with an optional version. Names must be plain package names and versions plain specifiers; a row can never carry a pip flag or an index URL. Import from requirements.txt fills the list from a file, and package search finds names as you type.
- Package sources: a Primary index URL and extra indexes, for a private index. Keep the credential out of the URL and use a build secret instead.
- System Packages: apt packages baked into the image, for example
ffmpeg. - Post-install Commands: shell commands run after the packages install,
for example
pip install -e .. - Environment Variables: set in every runtime on this environment. The
loader keys
LD_PRELOAD,LD_LIBRARY_PATH,PYTHONPATH,DYLD_INSERT_LIBRARIESandDYLD_LIBRARY_PATHare refused. Never put a credential here: use a secret. - Runtime Secrets and Build Secrets: the names of workspace secrets to deliver to the runtime or to the build; see Isolation and secrets.
- Visibility: recorded with the environment. Other people get access by sharing (below) or, for templates, from the platform.
The caps on each list are on the limits page.
Builds
Saving a recipe starts a build. The card shows its state: pending, building, success or failed. A build may take up to 45 minutes before it is abandoned; CUDA images with large ML dependencies take the longest. Builds cost 1 credit per minute of build time, failed builds included. Editing a recipe builds a new revision; runtimes already running on the old image are not affected.
From a running notebook
When you pip install in a session, the packages persist for the next
runtime on the same environment, but they are not part of the image. To bake
them in, use Save a copy as Environment in the notebook's File menu, or
accept Save as Environment when you press Stop. It runs pip freeze on
the runtime and creates a new environment whose build includes those
packages, so every future runtime on any machine starts with them and your
collaborators can launch the same thing. See
Packages in your runtime.
Sharing an environment
Share on an environment's card gives a named person access to it; it appears under Shared with me on their side and they can Fork it into their own account. What a recipient sees is redacted: the recipe shape, with environment-variable values blanked and build error text withheld. Secret names are visible and copied on fork, and they resolve against the launching workspace's secrets, never the author's, which is what makes a shared environment safe to launch. A recipient who edits gets a fork with a fresh id; the original is never modified.
Every share is scanned for credential-shaped strings first; see Sharing.
Card actions
| Action | Who | What it does |
|---|---|---|
| Edit Environment | Owner | Change the recipe and rebuild. |
| Duplicate | Anyone who can see it | A copy under your account, for templates and shared environments too. |
| Share | Owner | Give a named person access. |
| Delete Environment | Owner | Remove the environment and its image. Refused while a runtime is using it. |
An environment created in a workspace is deleted with that workspace; see Workspaces.
Related
- Packages in your runtime: what persists across stop and start without a rebuild.
- Isolation and secrets: secrets by name, build secrets, and what a shared recipe reveals.
- Limits: list sizes and refused keys.