Skip to content

Onboarding zot for Development

👉 zot is a production-ready, open-source, extensible OCI-native image registry, built for developers by developers.

Getting Started

Supported Developer Platforms

Development is officially supported on Linux and Apple MacOS platforms. However, development should be possible on any platform that supports the golang toolchain.

OS ARCH Platform
linux amd64 Intel-based Linux servers
linux arm64 ARM-based servers and Raspberry Pi4
darwin amd64 Intel-based MacOS
darwin arm64 ARM-based MacOS (Apple M1)

Supported platforms and architectures


Install golang (1.19+)

The zot project requires golang 1.19 or newer. You can follow the golang instructions to install the golang toolchain. After installation, make sure that the path environment variable or your IDE can find the toolchain.

Cloning zot

The zot registry code base is hosted on GitHub at

To clone the zot project, use this command:

$ git clone

Building zot

To build zot, execute the make command in the zot directory using the following general syntax:

$ make OS=os ARCH=architecture {binary | binary-minimal}

  • The operating system and architecture options are listed in the Supported platforms and architectures table. If an option is not specified, the defaults are linux and amd64.

  • The binary option builds the full zot binary image with all extensions.

  • The binary-minimal option builds the minimal distribution-spec conformant zot binary image without extensions, reducing the attack surface.

For example, to build a zot image with extensions for an Intel-based linux server, use the following command:

make OS=linux ARCH=amd64 binary

The make command builds an executable image in the zot/bin directory. The original filename of the zot executable image will indicate the build options. For example, the filename of an Intel-based linux minimal image is zot-linux-amd64-minimal.

Click here to view an example of the getting started process.

Running zot

The behavior of zot is controlled via configuration only. To launch the zot server, execute the following command:

$  bin/zot-linux-amd64 serve examples/config-minimal.json

Debugging zot

To produce a zot binary that includes extensive debugging information, build zot with the binary-debug option, as shown in this example:

make OS=linux ARCH=amd64 binary-debug

You can then attach and run a debugging tool such as Delve to the running zot process.

Delve is a powerful open-source debugger for the Go programming language. Downloads and documentation for Delve are available on GitHub at

Code Organization

The zot project codebase is organized as follows:

- pkg/              # Source code for all libraries
  - api/            # Source code for HTTP APIs
    - config/       # Global configuration model
  - storage/        # Source code for storage backends
  - cli/            # Source code for command line interface (cli)
  - common/         # Source code for common utility routines
  - compliance/     # Source code for dist-spec conformance tests
  - log/            # Source code for logging framework
  - test/           # Internal test scripts/data
  - extensions/     # Source code for all extensions
    - config/
    - sync/
    - monitoring/
    - sync/
  - exporter/       # Source code for metrics exporter
- cmd/              # Source code for binary main()s
  - zot/            # Source code for zot binary
  - zli/            # Source code for zot cli
  - zb/             # Source code for zb, the dist-spec benchmarking tool
- errors/           # Source code for error codes
- examples/         # Configuration examples
- swagger/          # Swagger integration
- docs/             # Documentation

Last update: September 1, 2023