---
title: Images
description: Go SDK - Image cache API reference
---
Local-only
Inspect and manage the local OCI image cache.
## Image
#### Image.Get()
```go
func (imageFactory) Get(ctx context.Context, reference string) (*ImageHandle, error)
```
```go
img, err := m.Image.Get(ctx, "python:3.12")
if err != nil {
return err
}
fmt.Println(img.ManifestDigest())
```
Fetch one cached image by reference. Returns `ErrImageNotFound` when no image with that reference is present in the local cache.
Parameters
ctxcontext.Context
Cancels the lookup.
referencestring
Image reference, e.g. "python:3.12".
Returns
Metadata handle for the cached image.
error
ErrImageNotFound when the reference is not cached.
#### Image.List()
```go
func (imageFactory) List(ctx context.Context) ([]*ImageHandle, error)
```
```go
images, err := m.Image.List(ctx)
if err != nil {
return err
}
for _, img := range images {
fmt.Println(img.Reference(), img.LayerCount())
}
```
Return every cached image, ordered by creation time (newest first).
Parameters
ctxcontext.Context
Cancels the listing.
Returns
All cached image handles, newest first.
error
Non-nil on failure.
#### Image.Inspect()
```go
func (imageFactory) Inspect(ctx context.Context, reference string) (*ImageDetail, error)
```
```go
detail, err := m.Image.Inspect(ctx, "python:3.12")
if err != nil {
return err
}
fmt.Println(detail.Config.Entrypoint, len(detail.Layers), "layers")
```
Return the full detail for a cached image: the [`ImageHandle`](#imagehandle) plus the parsed OCI config and the layer list.
Parameters
ctxcontext.Context
Cancels the inspection.
referencestring
Image reference, e.g. "python:3.12".
Returns
Handle, OCI config, and layers.
error
ErrImageNotFound when the reference is not cached.
#### Image.Remove()
```go
func (imageFactory) Remove(ctx context.Context, reference string, force bool) error
```
```go
if err := m.Image.Remove(ctx, "old:tag", false); err != nil {
return err
}
```
Delete a cached image. When `force` is false, sandboxes that still reference the image cause the call to fail with `ErrImageInUse`.
Parameters
ctxcontext.Context
Cancels the removal.
referencestring
Image reference to delete.
forcebool
When true, remove even if sandboxes still reference it.
Returns
error
ErrImageInUse when in use and force is false.
#### Image.Prune()
```go
func (imageFactory) Prune(ctx context.Context) (*ImagePruneReport, error)
```
```go
report, err := m.Image.Prune(ctx)
if err != nil {
return err
}
fmt.Println(report.LayersRemoved, "layers removed")
```
Remove cached image data that is not used by any sandbox or indexed snapshot. Returns a report tallying the image refs, manifests, layers, fsmeta files, and VMDK files removed, plus bytes reclaimed.
Parameters
ctxcontext.Context
Cancels the prune.
Returns
Summary of what was reclaimed.
error
Non-nil on failure.
---
#### Image.Load()
function
```go
func (imageFactory) Load(ctx context.Context, inputPath string, tags ...string) ([]*ImageHandle, error)
```
Import images from a local archive (a `docker save` tarball or an OCI Image Layout archive) into the cache, so locally built images can be used without a registry. Variadic `tags` apply extra references to the first image in the archive.
Parameters
ctxcontext.Context
Cancels the import.
inputPathstring
Path to the archive file.
tags...string
Extra references applied to the first image in the archive.
Returns
One handle for every image reference imported.
error
Non-nil on failure.
```go
// docker save my-image:latest -o my-image.tar
images, err := m.Image.Load(ctx, "my-image.tar", "app:local")
if err != nil {
return err
}
for _, img := range images {
fmt.Println(img.Reference())
}
```
---
#### Image.Save()
function
```go
func (imageFactory) Save(ctx context.Context, references []string, outputPath string, format ImageArchiveFormat) error
```
Export one or more cached images to an archive file at `outputPath`. `ImageArchiveDocker` (the default; `""` behaves the same) writes an archive loadable with `docker load`; `ImageArchiveOCI` writes an OCI Image Layout archive. Returns `ErrImageNotFound` when any reference is missing from the local cache.
Parameters
ctxcontext.Context
Cancels the export.
references[]string
Image references to export, e.g. "python:3.12".
outputPathstring
Path of the archive file to write.
ImageArchiveDocker (default; "" behaves the same) or ImageArchiveOCI.
Returns
error
ErrImageNotFound when any reference is not cached.
```go
err := m.Image.Save(ctx, []string{"python:3.12"}, "python.tar", m.ImageArchiveDocker)
if err != nil {
return err
}
```
---
## ImageHandle
Returned by Image.Get() · Image.List()
A metadata handle for a cached OCI image.
#### h.Reference()
```go
func (h *ImageHandle) Reference() string
```
The image reference, e.g. `"docker.io/library/python:3.12"`.
Returns
#### h.ManifestDigest()
```go
func (h *ImageHandle) ManifestDigest() string
```
The content-addressable manifest digest, or empty when unknown.
Returns
string
Manifest digest, or empty.
#### h.Architecture()
```go
func (h *ImageHandle) Architecture() string
```
The architecture resolved during the pull, or empty.
Returns
string
Architecture, or empty.
#### h.OS()
```go
func (h *ImageHandle) OS() string
```
The operating system resolved during the pull, or empty.
Returns
string
Operating system, or empty.
#### h.LayerCount()
```go
func (h *ImageHandle) LayerCount() uint
```
The number of layers in the image.
Returns
#### h.SizeBytes()
```go
func (h *ImageHandle) SizeBytes() *int64
```
The total image size in bytes, or `nil` when unknown.
Returns
*int64
Total size in bytes, or nil.
#### h.CreatedAt()
```go
func (h *ImageHandle) CreatedAt() time.Time
```
When this image was first pulled. Returns the zero `time.Time` when unknown.
Returns
time.Time
First-pulled time, or the zero value.
#### h.LastUsedAt()
```go
func (h *ImageHandle) LastUsedAt() time.Time
```
When this image was last referenced. Returns the zero `time.Time` when unknown.
Returns
time.Time
Last-referenced time, or the zero value.
#### h.Remove()
```go
func (h *ImageHandle) Remove(ctx context.Context, force bool) error
```
```go
img, err := m.Image.Get(ctx, "old:tag")
if err != nil {
return err
}
if err := img.Remove(ctx, false); err != nil {
return err
}
```
Delete this image. Equivalent to [`Image.Remove(ctx, h.Reference(), force)`](#image-remove). When `force` is false, sandboxes that still reference the image cause the call to fail with `ErrImageInUse`.
Parameters
ctxcontext.Context
Cancels the removal.
forcebool
When true, remove even if sandboxes still reference it.
Returns
error
ErrImageInUse when in use and force is false.
#### h.Inspect()
```go
func (h *ImageHandle) Inspect(ctx context.Context) (*ImageDetail, error)
```
```go
img, err := m.Image.Get(ctx, "python:3.12")
if err != nil {
return err
}
detail, err := img.Inspect(ctx)
if err != nil {
return err
}
fmt.Println(detail.Config.WorkingDir)
```
Return the full detail for this image. Equivalent to [`Image.Inspect(ctx, h.Reference())`](#image-inspect).
Parameters
ctxcontext.Context
Cancels the inspection.
Returns
Handle, OCI config, and layers.
error
Non-nil on failure.
## Types
### ImageDetail
Returned by Image.Inspect() · Inspect()
Bundles an [`ImageHandle`](#imagehandle) (embedded, so all its accessors are promoted) with the parsed OCI config and layer list.
```go
type ImageDetail struct {
*ImageHandle
Config *ImageConfig
Layers []ImageLayer
}
```
| Field | Type | Description |
|-------|------|-------------|
| `*ImageHandle` | [`*ImageHandle`](#imagehandle) | Embedded metadata handle (accessors promoted) |
| Config | [`*ImageConfig`](#imageconfig) | Parsed OCI config block |
| Layers | `[]`[`ImageLayer`](#imagelayer) | Layers in manifest order |
### ImageConfig
Used by ImageDetail.Config
The parsed OCI config block.
| Field | Type | Description |
|-------|------|-------------|
| Digest | `string` | Config blob digest |
| Env | `[]string` | Environment variables (`KEY=VALUE`) |
| Cmd | `[]string` | Default command |
| Entrypoint | `[]string` | Entrypoint |
| WorkingDir | `string` | Working directory |
| User | `string` | Default user |
| Labels | `map[string]string` | OCI labels |
| StopSignal | `string` | Stop signal |
### ImageLayer
Used by ImageDetail.Layers
One layer of an image manifest.
| Field | Type | Description |
|-------|------|-------------|
| DiffID | `string` | Uncompressed layer diff ID |
| BlobDigest | `string` | Compressed blob digest |
| MediaType | `string` | Layer media type |
| CompressedSizeBytes | `*int64` | Compressed size in bytes, or `nil` |
| ErofsSizeBytes | `*int64` | EROFS size in bytes, or `nil` |
| Position | `int32` | Index in the layer stack |
### ImagePruneReport
Returned by Image.Prune()
Summarizes the artifacts removed by [`Image.Prune`](#image-prune).
| Field | Type | Description |
|-------|------|-------------|
| ImageRefsRemoved | `uint32` | Image references removed |
| ManifestsRemoved | `uint32` | Manifests removed |
| LayersRemoved | `uint32` | Layers removed |
| FsmetaRemoved | `uint32` | Fsmeta files removed |
| VMDKRemoved | `uint32` | VMDK files removed |
| BytesReclaimed | `*uint64` | Bytes reclaimed, or `nil` when unknown |
### ImageArchiveFormat
type
Used by Image.Save()
Selects the archive layout written by [`Image.Save`](#image-save).
```go
type ImageArchiveFormat string
```
| Constant | Value | Description |
|----------|-------|-------------|
| `ImageArchiveDocker` | `"docker"` | `docker save` compatible archive, loadable with `docker load` (the default; the empty string means the same) |
| `ImageArchiveOCI` | `"oci"` | OCI Image Layout archive |