Skip to main content
Check Image supports multiple image sources using a transport-based syntax compatible with Skopeo. This allows you to validate images from Docker registries, OCI layout directories, and archive files.

​
Transport Prefixes

Transport prefixes tell Check Image where to load the image from. When no prefix is specified, the tool tries the local Docker daemon first, then falls back to a remote registry.

​
Supported Transports

docker://

Docker daemon or remote registry (default)

oci:

OCI layout directory on disk

oci-archive:

OCI tarball archive

docker-archive:

Docker tarball created with docker save

​
Default Behavior (No Prefix)

When you don’t specify a transport prefix, Check Image uses a fallback strategy:
  1. Try Docker daemon: Looks for the image in the local Docker daemon
  2. Fall back to registry: If not found locally, fetches from the remote registry
check-image age nginx:latest
check-image size docker.io/nginx:latest --max-size 100
When no tag is specified, :latest is automatically appended to the image reference.

​
OCI Layout Directory (oci:)

Load images from an OCI image layout directory on disk. This is useful for validating images that have been built or exported to a directory structure.

​
Syntax

oci:/path/to/layout:tag
oci:/path/to/layout@sha256:digest

​
Examples

check-image age oci:/path/to/layout:latest
check-image size oci:./nginx-layout:v1.23 --max-size 100
When using the oci: transport, you must specify either a tag or a digest. The tool does not fall back to other sources.

​
OCI Archive (oci-archive:)

Load images from OCI tarball archives. The archive is extracted to a temporary directory during processing and automatically cleaned up afterward.

​
Syntax

oci-archive:/path/to/image.tar:tag
oci-archive:/path/to/image.tar@sha256:digest

​
Examples

check-image age oci-archive:/path/to/image.tar:latest
check-image size oci-archive:./exported-image.tar:1.0 --max-size 100

​
Security Features

The extraction process validates all paths to prevent malicious archives from writing files outside the temporary directory.
A 5GB decompression limit prevents decompression bomb attacks. If an archive expands beyond this limit, the operation is aborted.
Both gzipped (.gz, .tgz) and uncompressed tarballs are supported.

​
Creating OCI Archives

skopeo copy docker://nginx:latest oci-archive:nginx.tar:latest

​
Docker Archive (docker-archive:)

Load images from Docker tarball archives created with docker save. This format is compatible with Docker’s native save/load mechanism.

​
Syntax

docker-archive:/path/to/saved.tar:image:tag
The tag includes the full image name and tag as it appears in the archive (e.g., nginx:latest, myapp:2.0).

​
Examples

check-image age docker-archive:/path/to/saved.tar:nginx:latest
check-image size docker-archive:./backup.tar:myapp:2.0

​
Creating Docker Archives

docker save -o nginx.tar nginx:latest
docker save -o multi.tar nginx:latest alpine:latest

​
Fallback Behavior

Important: When you use an explicit transport prefix (oci:, oci-archive:, docker-archive:), Check Image only attempts to load from that source. There is no fallback to other sources.
# Only tries OCI layout - no fallback
check-image age oci:/path/to/layout:latest

# Only tries OCI archive - no fallback
check-image size oci-archive:./image.tar:latest

# Only tries Docker archive - no fallback
check-image age docker-archive:./saved.tar:nginx:latest

​
Special Cases

​
Registry Command Validation

The registry command validates that an image comes from a trusted registry. This check is automatically skipped for non-registry transports: 
# Registry check runs
check-image registry nginx:latest --registry-policy policy.json

# Registry check is skipped (not applicable)
check-image registry oci:./layout:latest --registry-policy policy.json
When the registry check is skipped due to transport type, the validation passes by default and the output indicates the check was skipped.

​
Windows Path Support

The transport parser handles Windows drive letters correctly:
Windows paths
check-image age oci:C:\images\layout:latest
check-image size oci-archive:D:\exports\image.tar:v1.0

​
Best Practices

1

Use explicit transports for predictable behavior

When working with files or directories, always use the appropriate transport prefix (oci:, oci-archive:, docker-archive:) to avoid ambiguity.
2

Prefer OCI formats for portability

OCI layout and OCI archives are vendor-neutral formats that work across different container runtimes.
3

Specify digests for reproducibility

When possible, use digest references (@sha256:...) instead of tags for guaranteed reproducibility.
4

Clean up archives after validation

Archive files can be large. Remove them after validation to save disk space.

Authentication

Learn how to authenticate with private registries

Configuration Files

Understand policy and configuration file formats

Output Formats

Control output format and color modes

Commands

Explore all available validation commands

Build docs developers (and LLMs) love

Get started for freeTalk to us