Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/psviderski/uncloud/llms.txt

Use this file to discover all available pages before exploring further.

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