# Image families

How an image family resolves to its current platform-provided image, what its metadata tells you about upstream support, and what happens when one is withdrawn.

An image family is a stable name for a line of platform-provided images, such as `ubuntu-22-04-minimal`. A launch that names a family gets whichever image the platform has designated as current for it. A launch that names an image URN gets exactly that image until you change it.

Launch by family to pick up rebuilt images automatically. Launch by image URN to pin the image you tested against.

## Launching by family [#launching-by-family]

The `launchInstance` mutation accepts `imageFamily` in place of `imageUrn`. Set exactly one of the two. The `origin compute launch-instance` command has no family option and takes `--image-urn` only. To find a family’s current image for the CLI, query images through the API and pick the platform-provided image whose `family` matches and whose `isFamilyCurrent` is `true`, then launch by its URN.

You can make the same pick from the output of `origin compute list-images`, which includes `family` and `isFamilyCurrent` for platform-provided images. For example, with `jq`:

```sh
origin compute list-images --project-urn <project-urn> \
  | jq -r '.. | objects
      | select(.family? == "<family-slug>" and .isFamilyCurrent? == true)
      | .urn'
```

Pass the printed URN to `launch-instance` as `--image-urn`. The CLI help for `list-image-families` mentions an `--image-family` option, but `launch-instance` doesn’t accept one.

A family resolves separately per CPU architecture. With `X86_64` as the only architecture, a family resolves to one image.

A new image is published into a family first and designated current afterward, so a family can briefly have a newer image that isn’t current yet. A family that has no current image refuses launches with “no image is currently published for this family”.

## Family metadata [#family-metadata]

Read the families with the `imageFamilies` query or `origin compute list-image-families`. No permission is needed.

| Field | Meaning |
| --- | --- |
| `slug` | The name to pass as `imageFamily`, for example `ubuntu-22-04-minimal`. |
| `vendor` | Who publishes the upstream release, for example `Canonical`. |
| `os` | The operating system the family tracks, for example `ubuntu`. |
| `osVersion` | The release, for example `22.04`. |
| `description` | A human-readable description. |
| `supportEndsAt` | When the upstream vendor stops supporting this release, if a date is known. |

`supportEndsAt` is advisory. No launch is refused on it, and running instances aren’t affected. Treat it as notice to move to a newer family.

## Stable names and withdrawn families [#stable-names-and-withdrawn-families]

A family is never renamed, and a name is never reused for a different line. A name in your scripts keeps meaning what it meant.

A family can be withdrawn when a newer line supersedes it. A withdrawn family:

- Drops out of `imageFamilies` and `list-image-families`.
- Refuses launches by its name, with `image family '<slug>' is retired and launches nothing`.
- Doesn’t affect anything you’re already running. The images published under it stay listed and can still be launched by URN.

## Related [#related]

- [Images](/docs/compute/images)
- [Launch an instance](/docs/compute/instances/launch)
- [`list-image-families` reference](/docs/compute/reference/cli#list-image-families)