Skip to main content
List container images stored on machines in your cluster, showing their tags, platforms, size, and which machines they’re on.

​
Usage

uc images [REPO:[TAG]] [flags]

​
Arguments

​
REPO:[TAG]
string
Filter images by repository name and optionally tag. Supports wildcards in the tag.

​
Flags

​
-m, --machine
string[]
Filter images by machine name or ID. Can be specified multiple times or as a comma-separated list. Default is to include all machines.

​
Output

The command displays a table with:
  • IMAGE ID - First 12 characters of the image ID
  • NAME - Image repository and tag
  • PLATFORMS - Supported platforms (for example, linux/amd64, linux/arm64)
  • CREATED - How long ago the image was created
  • SIZE - Image size
  • IN USE - Whether the image is used by containers (● = in use, ○ = not in use, - = unknown)
  • STORE - Image store (docker or containerd)
  • MACHINE - Which machine has this image

​
Examples

​
List all images

uc images
Example output: 
IMAGE ID      NAME                PLATFORMS        CREATED        SIZE      IN USE   STORE   MACHINE
abc123def456  nginx:latest        linux/amd64      2 days ago     142MB     ●        docker  vps1
abc123def456  nginx:latest        linux/amd64      2 days ago     142MB     ●        docker  vps2
def456ghi789  postgres:16         linux/amd64      1 week ago     379MB     ●        docker  vps1
ghi789jkl012  myapp:v2            linux/amd64      3 hours ago    245MB     ○        docker  vps1

​
List images on a specific machine

uc images -m vps1

​
List images on multiple machines

uc images -m vps1,vps2

​
Filter by image name

uc images nginx
Shows all nginx images with any tag.

​
Filter by image name and tag

uc images nginx:latest

​
Filter with wildcards

uc images "myapp:1.*"
Shows all images matching myapp:1.0, myapp:1.1, etc.

​
Understanding the Output

​
Image ID

The first 12 characters of the image’s SHA256 digest. Same ID means the same image content.

​
Platforms

Shows which CPU architectures the image supports. Multi-platform images show multiple platforms.

​
In Use Indicator

  • ● (filled circle) - Image is used by one or more containers
  • ○ (empty circle) - Image is not used by any containers (can be cleaned up)
  • - - In-use information not available (requires Docker API 1.51+)

​
Image Store

Most images are in the docker store. Some may be in containerd if you’re using containerd directly.

​
Finding Unused Images

To find images that can be safely removed: 
uc images | grep ○
This shows images not used by any containers.

​
Multi-Platform Images

Some images support multiple platforms: 
IMAGE ID      NAME                PLATFORMS                      SIZE
abc123def456  nginx:latest        linux/amd64 linux/arm64        142MB
These work on both AMD64 and ARM64 machines.

​
Image Distribution

The same image on multiple machines has the same ID: 
IMAGE ID      NAME           MACHINE
abc123def456  myapp:latest   vps1
abc123def456  myapp:latest   vps2
This confirms the same image content is on both machines.

​
Use Cases

​
Check Image Availability

Before deploying, verify images are on the right machines: 
uc images myapp:v2

​
Find Large Images

Identify images taking up disk space: 
uc images | sort -k5 -h

​
Verify Image Push

After pushing an image, confirm it arrived: 
uc build --push
uc images myapp:latest

​
Clean Up Unused Images

Find images not in use: 
uc images | grep ○
Then remove them manually via SSH or using docker image prune on each machine.

Build docs developers (and LLMs) love

Get started for freeTalk to us