docs/sdk/python/images.mdx
Image is the static namespace for two related things: configuring an explicit rootfs source for a sandbox (Image.oci, Image.bind, Image.disk), and managing the local OCI image cache that sandbox creation pulls into (get, list, inspect, remove, prune, load, save). Cache operations require a local backend. See Sandbox for the image= and pull_policy= creation kwargs.
from microsandbox import Image
from microsandbox import Image, Sandbox
# Pull happens implicitly on creation
async with await Sandbox.create("api", image="python:3.12") as sb:
await sb.exec("python", ["-V"])
# Later, inspect and prune the local cache
for image in await Image.list():
print(image.reference, image.layer_count)
report = await Image.prune()
print(f"reclaimed {report.bytes_reclaimed} bytes")
These static methods return an ImageSource you can pass as the image= kwarg to Sandbox.create(). A plain string also works (image="python:3.12"); use the factory when you need OCI-only options like the writable upper size, or to be explicit about a bind or disk source.
@staticmethod
def oci(reference: str, *, upper_size_mib: int | None = None) -> ImageSource
sb = await Sandbox.create(
"api",
image=Image.oci("python:3.12", upper_size_mib=8192),
)
Create an OCI image rootfs source. Use upper_size_mib to size the writable overlay upper layer; otherwise the default applies.
@staticmethod
def bind(path: str) -> ImageSource
sb = await Sandbox.create("api", image=Image.bind("/srv/rootfs"))
Create a rootfs source that binds a host directory as the guest root filesystem.
<p className="msb-label">Parameters</p> <div className="msb-params"> <div className="msb-param"> <div className="msb-param-key"><code>path</code><span className="msb-type">str</span></div> <div className="msb-param-desc">Host directory to use as the rootfs.</div> </div> </div> <p className="msb-label">Returns</p> <div className="msb-params"> <div className="msb-param"> <div className="msb-param-key"><a className="msb-type" href="#imagesource">ImageSource</a></div> <div className="msb-param-desc">Rootfs source for <code>image=</code>.</div> </div> </div>@staticmethod
def disk(path: str, *, fstype: str | None = None) -> ImageSource
sb = await Sandbox.create(
"api",
image=Image.disk("/data/root.qcow2", fstype="ext4"),
)
Create a rootfs source backed by a disk image. The format is inferred from the file extension. Pass fstype when the filesystem type cannot be auto-detected.
These static methods inspect and prune images already pulled into the local OCI cache. They require a local backend; on a cloud backend they raise UnsupportedError.
@staticmethod
async def get(reference: str) -> ImageHandle
handle = await Image.get("python:3.12")
print(handle.reference, handle.layer_count)
Fetch one cached image by reference. Raises ImageNotFoundError when the image is not present in the local cache.
@staticmethod
async def list() -> list[ImageHandle]
for image in await Image.list():
print(image.reference, image.size_bytes)
Return every cached image.
<p className="msb-label">Returns</p> <div className="msb-params"> <div className="msb-param"> <div className="msb-param-key"><a className="msb-type" href="#imagehandle">list[ImageHandle]</a></div> <div className="msb-param-desc">All cached image handles.</div> </div> </div>@staticmethod
async def inspect(reference: str) -> ImageDetail
detail = await Image.inspect("python:3.12")
print(detail.handle.reference)
for layer in detail.layers:
print(layer.position, layer.diff_id)
Return handle metadata plus the parsed OCI config and per-layer detail.
<p className="msb-label">Parameters</p> <div className="msb-params"> <div className="msb-param"> <div className="msb-param-key"><code>reference</code><span className="msb-type">str</span></div> <div className="msb-param-desc">Image reference to inspect.</div> </div> </div> <p className="msb-label">Returns</p> <div className="msb-params"> <div className="msb-param"> <div className="msb-param-key"><a className="msb-type" href="#imagedetail">ImageDetail</a></div> <div className="msb-param-desc">Handle, OCI config, and layers.</div> </div> </div>@staticmethod
async def remove(reference: str, *, force: bool = False) -> None
await Image.remove("python:3.12", force=True)
Delete a cached image. When force is False, an image still referenced by one or more sandboxes raises ImageInUseError; pass force=True to remove it anyway.
@staticmethod
async def prune() -> ImagePruneReport
report = await Image.prune()
print(f"{report.layers_removed} layers, {report.bytes_reclaimed} bytes")
Remove cached image data that is not used by any sandbox or indexed snapshot. The returned report counts the removed refs, manifests, layers, fsmeta files, and VMDK files, plus any measured bytes reclaimed.
<p className="msb-label">Returns</p> <div className="msb-params"> <div className="msb-param"> <div className="msb-param-key"><a className="msb-type" href="#imageprunereport">ImagePruneReport</a></div> <div className="msb-param-desc">Counts of removed data and bytes reclaimed.</div> </div> </div> <Accordion title="Example">report = await Image.prune()
print(f"{report.layers_removed} layers, {report.bytes_reclaimed} bytes")
@staticmethod
async def load(input_path: str, *, tag: str | None = None) -> list[ImageHandle]
Import images from a local archive into the cache. Accepts docker save tarballs and OCI Image Layout archives, so locally built images can be used without going through a registry.
# docker save my-image:latest -o my-image.tar
images = await Image.load(input_path="my-image.tar", tag="app:local")
for image in images:
print(image.reference, image.layer_count)
# Or pipe it in: docker save my-image:latest | python app.py
images = await Image.load(input_path="-")
@staticmethod
async def save(reference: str | Sequence[str], *, output_path: str, format: str = "docker") -> None
Export one or more cached images to an archive file. Raises ImageNotFoundError when any reference is not in the local cache, and ValueError for an unknown format or an empty reference list.
await Image.save("python:3.12", output_path="python.tar")
await Image.save("python:3.12", output_path="python-oci.tar", format="oci")
await Image.save(["python:3.12", "app:local"], output_path="bundle.tar")
Explicit rootfs image source. Build one with Image.oci(), Image.bind(), or Image.disk(), then pass it as the image= kwarg to Sandbox.create(). A frozen dataclass; treat its fields as opaque.
| Field | Type | Description |
|---|---|---|
_type | str | Source kind: "oci", "bind", or "disk" |
_path | str | None | Host path for bind / disk sources |
_reference | str | None | OCI reference for oci sources |
_upper_size_mib | int | None | Writable overlay upper size in MiB (OCI only) |
_fstype | str | None | Filesystem type for disk sources |
_format | DiskImageFormat | None | Disk image format (inferred from extension) |
A lightweight handle to a cached OCI image, returned by Image.get(), Image.list(), and Image.load(). Properties are read-only attributes; the two methods are async.
| Property / Method | Type | Description |
|---|---|---|
reference | str | Image reference |
size_bytes | int | None | Total size in bytes, or None when unknown |
manifest_digest | str | None | Content-addressable manifest digest |
architecture | str | None | Resolved architecture |
os | str | None | Resolved operating system |
layer_count | int | Number of layers |
last_used_at | float | None | Last referenced time, milliseconds since epoch |
created_at | float | None | First-pulled time, milliseconds since epoch |
await inspect() | ImageDetail | Fetch full detail for this image |
await remove(*, force=False) | None | Delete this image (raises ImageInUseError unless force) |
Full detail for a cached image: the core handle, the parsed OCI config block, and per-layer metadata.
| Property | Type | Description |
|---|---|---|
handle | ImageHandle | Core cached image metadata |
config | ImageConfigDetail | None | Parsed OCI config block |
layers | list[ImageLayerDetail] | Layers in bottom-to-top order |
OCI image config fields extracted from the local cache.
| Property | Type | Description |
|---|---|---|
digest | str | Config blob digest |
env | list[str] | Environment variables (KEY=value) |
cmd | list[str] | None | Default command |
entrypoint | list[str] | None | Image entrypoint |
working_dir | str | None | Default working directory |
user | str | None | Default user |
labels | dict[str, Any] | None | OCI labels |
stop_signal | str | None | Configured stop signal |
Metadata for a single image layer.
| Property | Type | Description |
|---|---|---|
diff_id | str | Uncompressed layer diff id |
blob_digest | str | Compressed blob digest |
media_type | str | None | Layer media type |
compressed_size_bytes | int | None | Compressed size in bytes |
erofs_size_bytes | int | None | Size of the generated EROFS sidecar in bytes |
position | int | Layer position (bottom to top) |
Summary of cached image data removed by Image.prune().
| Property | Type | Description |
|---|---|---|
image_refs_removed | int | Number of image refs removed |
manifests_removed | int | Number of manifests removed |
layers_removed | int | Number of layer blobs removed |
fsmeta_removed | int | Number of fsmeta sidecar files removed |
vmdk_removed | int | Number of VMDK files removed |
bytes_reclaimed | int | None | Measured bytes reclaimed, or None when not measured |
Disk image container format. A StrEnum, so the string values are accepted directly.
| Value | Description |
|---|---|
"qcow2" | QEMU copy-on-write v2 |
"raw" | Raw block image |
"vmdk" | VMware disk image |
Image operations raise these typed exceptions, all subclasses of MicrosandboxError.
| Exception | Raised when |
|---|---|
ImageNotFoundError | The image reference could not be resolved in the local cache |
ImageInUseError | The image is still referenced by one or more sandboxes (and force was not set) |
ImagePullFailedError | An image pull failed |
UnsupportedError | Cache operations were attempted on a backend that lacks a local cache |