Zot stores OCI content without a proprietary layout
Zot is a registry for container images and other artifacts that follow the OCI image and distribution specifications. Content stays in the OCI image layout on disk, giving operators an escape hatch from a registry-specific format. The project ships full and minimal binaries for Linux and macOS on Intel and ARM.
The full build names 9 extensions: sync, search, scrub, metrics, lint, UI, management, user preferences, and image trust. Search can add GraphQL and Trivy-backed CVE data. Image trust checks Cosign keys and Notation certificates. Sync supports periodic and on-demand pulls from upstream registries. Each enabled extension adds configuration and background work.
What happened when we ran it
Our run used commit 2103147 in an unprivileged Go 1.24 Debian container with 3 CPUs, 8 GB of RAM, and no secrets. Dependency installation succeeded in 177 seconds and pulled 1,247 packages. The build succeeded in 30 seconds. The checkout itself contained 761 files, roughly 248,073 lines of source, and occupied 11.7 MB before installation.
Tests ran for 713 seconds and exited with code 1. The Go summary counted 48 passed packages and 13 failed out of 61. Its final lines named TestCopyFiles in pkg/test/common, then TestImageBuilder and TestPredefinedImages in pkg/test/image-utils. The supplied log tail contains no error explaining those failures, so we cannot assign a cause. This checkout built successfully and did not pass its full test command.
One service still needs explicit auth and storage decisions
Zot starts with a JSON or YAML file passed to zot serve. The binary emits a draft 7 JSON Schema and verifies a candidate configuration before launch. Authentication includes mutual TLS, htpasswd, LDAP, bearer tokens, and OpenID. Browser OpenID login does not work for normal image clients, so the configuration guide steers those users toward API keys.
Storage can be local or backed by S3, Azure Blob, and GCS. Local deduplication depends on hard links, while garbage collection and retention can delete unreferenced content. Multiple replicas require shared remote storage, a load balancer, and suitable shared metadata and session stores. A basic registry listens on port 5000.
Nine extensions make the full binary much more than a blob server
Search exposes image metadata and can attach vulnerability data from Trivy. Sync filters repositories and tags, checks signatures if configured, and supports multiple upstream URLs. Scrubbing checks stored content, metrics feed monitoring, and the UI gives humans a catalog. The minimal binary suits operators who value conformance and a smaller attack surface over those extras.
These jobs touch live storage. Garbage collection settings need to match push patterns, while retention uses ordered repository policies and tag expressions. Fast restart can skip a storage walk for a 1 TB or larger S3 backend. The source documentation warns that out-of-band storage changes may then leave metadata inconsistent, so the shortcut is disabled by default.
Issue 4399 reports 93 of 131 first pulls failing
Open issue 4399 describes v2.1.20 running as a per-node on-demand cache. During a concurrent first pull, 93 of 131 CI jobs failed because readers saw a repository directory before its index.json was available. Open issue 4390 reports another burst failure: a shared Redis lock error while updating download statistics turns an otherwise valid manifest read into HTTP 500.
Those reports target specific scale-out cache configurations. Issue 4323 explains that an uncached on-demand request waits while the full image is copied locally, sending no bytes to the first client until that work finishes. A distant upstream or large image can hit a client timeout, after which a retry succeeds from the populated cache.
The 2,223-character README sends operators elsewhere for detail
The root README establishes the OCI-only scope and links the documentation, but it contains no quick-start command or feature map. The repository's examples/README.md is more useful: it documents schema generation, configuration verification, storage, authentication, retention, cache drivers, sync, search, and CVE scanning. Example files cover local, cloud, Redis, LDAP, TLS, OIDC, metrics, and cluster cases.
Cross-check the documentation against the release you deploy. The separate administrator guide includes older examples and paths, while the source-tree reference carries newer settings such as fast restart and API keys. For v2.1.20, generate the schema from the same binary and run zot verify during deployment.
Version 2.1.20 is released, and September issue work is active
Zot v2.1.20 was published on 2026-08-04. GitHub showed 2,698 stars and 87 combined open issues and pull requests on 2026-09-04. The default branch was pushed that day, with recent work on authentication, configuration reloads, concurrent pulls, garbage collection, and ecosystem tests. Code and issue activity both show ongoing maintenance.
The 30-second build earns a trial, while cache behavior decides adoption
Zot's attraction is a narrow foundation with optional registry conveniences. The 30-second build and small checkout make source inspection approachable, though 13 failed test packages prevent a clean recommendation from our run. Start with a basic private registry. Add sync, Redis metadata, retention, and replicas one at a time with concurrent pull tests.
CNCF Distribution is a plainer core when separate services will handle policy and UI. Harbor suits teams that want a larger governance product, while Quay offers another full registry application. Choose Zot when OCI-native storage and selective extensions are more appealing, then prove first-pull behavior with the same clients and fan-out your cluster will use.