Images

Anything a workload needs beyond the standard library goes in its Image, along with the Python version it runs. LazyCloud builds the image in the cloud, so nothing installs on your machine.

Install remote dependencies

from lazycloud import App, Image

app = App("audio")

image = (
    Image(python_version="3.12")
    .add_commands(["apt-get update && apt-get install -y ffmpeg"])
)


@app.function(image=image)
def ffmpeg_version() -> str:
    import subprocess

    return subprocess.check_output(["ffmpeg", "-version"], text=True).splitlines()[0]

uv run lazycloud run audio:ffmpeg_version prints the ffmpeg version from the cloud container, and your machine never needs ffmpeg. .add_python_packages(["httpx"]) adds a Python package. Image() alone is the managed Python 3.12 image, and Python 3.10 through 3.14, or a patch release such as 3.12.11, are available. Images are cached by content, so an unchanged image never rebuilds.

Create an image from a project

A factory builds from the project’s own dependency files:

from lazycloud import Image

image = Image.from_uv(".")

The build reads the directory’s pyproject.toml, lockfile, and .python-version, plus any local path dependencies inside it. It installs dependencies only. Your own code reaches the container through source sync, so editing it never rebuilds the image, and code under src/ still imports.

uv

image = Image.from_uv(".", extras=["gpu"], groups=["inference"])

Needs pyproject.toml and uv.lock, and installs exactly what’s locked. Dependency groups, including dev, install only when groups names them.

Poetry

image = Image.from_poetry(".", extras=["gpu"], groups=["inference"])

Needs pyproject.toml and poetry.lock, and installs the locked main dependencies plus the selected groups and extras.

Standard pyproject.toml

image = Image.from_pyproject(".", extras=["gpu"], groups=["inference"])

Reads standard [project] metadata and [dependency-groups] and resolves versions at build time, with no lockfile. from_uv and from_poetry are the locked options.

Micromamba

environment.yml

channels:
  - conda-forge
dependencies:
  - python=3.12
  - numpy
  - pip:
      - httpx==0.28.1

image = Image.from_micromamba("environment.yml")

The environment file supplies Python, channels, Conda packages, and pip dependencies. Unpinned packages resolve at build time.

Python selection

An explicit python_version overrides the project’s interpreter pin:

image = Image.from_uv(".", python_version="3.12.11")

Otherwise the project’s .python-version, or Micromamba’s python= entry, decides, with 3.12 as the fallback. An unsupported pin fails. Factories return an ordinary image that extends like any other:

image = Image.from_uv(".").add_commands([
    "apt-get update && apt-get install -y ffmpeg"
])

All four also accept base_image, base_image_creds, and architecture:

image = Image.from_uv(
    ".", base_image="nvidia/cuda:12.3.1-runtime-ubuntu22.04"
)

The CLI still imports your module locally, so top-level imports need to resolve on your machine. Remote-only packages can be imported inside the function.

Constructor

Image(
    python_version="3.12",         # supported minor or exact patch release
    python_packages=["httpx"],     # package specs, or a path to requirements.txt
    commands=["python --version"], # shell commands run during the build
    base_image=None,               # start from a registry image instead
    base_image_creds=None,         # registry credentials, see below
    env_vars=None,                 # environment variables baked into the image
)

Builder methods

Each returns the image, so they chain.

add_python_packages(packages) installs packages. Pass a list of specs or a path to a requirements.txt.
add_commands(commands) runs shell commands during the build.
add_local_path(pattern="*") includes matching local files in the build context.
add_micromamba_packages(packages, channels=[...]) adds packages to an image created with from_micromamba().
with_envs(env_vars, clear=False) sets environment variables from a mapping, "KEY=value" strings, or a sequence of them.
with_secrets(secrets) makes workspace secrets available during the build.
with_docker() installs Docker so containers using the image can run their own daemon.
build_with_gpu(hint) runs the build on a GPU worker of the given model.

Start from an existing image

gpu_image = Image.from_registry(
    "nvidia/cuda:12.3.1-runtime-ubuntu22.04", python_version="3.11"
)
custom_image = Image.from_dockerfile("./Dockerfile", context_dir=".")

Image.from_id(image_id) reuses a sandbox filesystem snapshot, given the ID the snapshot returned.

Private registries

credentials names environment variables that LazyCloud reads on your machine when the image builds, so values stay out of code:

image = Image.from_registry(
    "ghcr.io/acme/models:latest",
    credentials=["GITHUB_USERNAME", "GITHUB_TOKEN"],
)

A dict maps the same names to values you’ve already loaded: {"GITHUB_USERNAME": "acme-bot", "GITHUB_TOKEN": os.environ["CI_GHCR_TOKEN"]}. A listed variable that isn’t set stops the build before it starts. The names are fixed per registry, and any other name is ignored:

Registry	Names
GitHub, `ghcr.io`	`GITHUB_USERNAME` and `GITHUB_TOKEN`
Amazon ECR	`AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`, optional `AWS_SESSION_TOKEN` and `AWS_REGION`
Google, `gcr.io` and `pkg.dev`	`GCP_ACCESS_TOKEN` or `GOOGLE_APPLICATION_CREDENTIALS`, optional `GCP_PROJECT_ID`
Azure, `azurecr.io`	`AZURE_CLIENT_ID`, `AZURE_CLIENT_SECRET`, optional `AZURE_TENANT_ID`
NVIDIA, `nvcr.io`	`NGC_API_KEY`
Docker Hub and others	`DOCKERHUB_TOKEN`, or `REGISTRY_USERNAME` and `REGISTRY_PASSWORD`

GOOGLE_APPLICATION_CREDENTIALS can be a file path or the JSON itself. The constructor and project factories take the same value as base_image_creds.

Getting started

Core concepts

CLI reference

Examples

Account

Install remote dependencies

Create an image from a project

uv

Poetry

Standard pyproject.toml

Micromamba

Python selection

Constructor

Builder methods

Start from an existing image

Private registries

​Install remote dependencies

​Create an image from a project

​uv

​Poetry

​Standard pyproject.toml

​Micromamba

​Python selection

​Constructor

​Builder methods

​Start from an existing image

​Private registries

Install remote dependencies

Create an image from a project

uv

Poetry

Standard pyproject.toml

Micromamba

Python selection

Constructor

Builder methods

Start from an existing image

Private registries