How to install img on Ubuntu?

Install the uidmap and libseccomp-dev packages, download the binary from the releases page, and enable user namespace support by setting /proc/sys/kernel/unprivileged_userns_clone to 1. Detailed steps are in the README's installation section.

Is img faster than Docker build?

Yes, img can be more cache-efficient and execute build stages concurrently due to BuildKit's DAG solver. The README references benchmarks from buildbench showing performance comparisons.

Can img build images for ARM architecture?

Yes, using the --platform flag, img supports builds for ARM (e.g., linux/arm64), but RUN commands require QEMU emulation with binfmt_misc flags set to OCF, as noted in the cross-platform section.

How to use img with Kubernetes?

Since v0.5.11, img can run in Kubernetes without privileged containers, but it requires security annotations for seccomp and AppArmor to be unconfined, and PID isolation needs procMount set to Unmasked.

What's the difference between img and BuildKit?

img is a CLI tool that wraps BuildKit to provide unprivileged execution and a Docker-compatible interface, while BuildKit is the underlying build engine also used by Docker. img adds security-focused features like daemon-less operation.

How to fix permission errors in img?

Ensure /etc/subuid and /etc/subgid have at least 65536 entries, install newuidmap, and verify user namespace is enabled. The README's 'How It Works' section details unprivileged mounting requirements.

Open-Awesome

img

MITGov0.5.11

A standalone, daemon-less, unprivileged container image builder compatible with Dockerfile and OCI.

Visit Website GitHub

4.0k stars233 forks0 contributors

What is img?

img is a standalone, daemon-less container image builder that allows users to build Dockerfile and OCI-compatible images without requiring root privileges. It solves the problem of secure image building in environments where users lack administrative access, such as HPC clusters or academic institutions, by operating entirely as an unprivileged process.

Target Audience

Developers, system administrators, and researchers in environments like HPC, academia, or enterprises with strict security policies who need to build container images without root access or a Docker daemon.

Value Proposition

Developers choose img for its security-first approach, allowing unprivileged image building while maintaining full Docker CLI compatibility. Its use of BuildKit enables superior cache efficiency and concurrent builds, offering performance benefits over traditional Docker builds.

Overview

Standalone, daemon-less, unprivileged Dockerfile and OCI compatible container image builder.

Use Cases

Best For

Building container images in shared or locked-down environments without root access
CI/CD pipelines where running a Docker daemon is undesirable or restricted
Academic and HPC clusters with LDAP or non-root user constraints
Kubernetes-based image building without privileged containers
Cross-platform container image builds for multiple architectures
Secure image building workflows that prioritize least-privilege principles

Not Ideal For

Teams heavily integrated with Docker's full orchestration ecosystem (e.g., Docker Compose, Swarm), as img focuses solely on image building and lacks those features
Developers on macOS or Windows seeking a native, out-of-the-box experience without container workarounds, since img's primary support is Linux
Environments with strict, unpatched kernel versions that cannot support unprivileged overlayfs, forcing reliance on slower or less efficient backends

Pros & Cons

Pros

Daemon-less Operation

Runs as a standalone binary without a background service, reducing resource overhead and simplifying deployment in restricted environments.

Unprivileged Security

Builds images as a non-root user by leveraging user namespaces and SUID binaries, making it ideal for multi-user setups like HPC and academia.

Docker-compatible UX

Commands mirror Docker's CLI for build, tag, push, and more, allowing seamless adoption by swapping 'docker' with 'img' in existing scripts.

Concurrent Build Efficiency

Uses BuildKit's DAG solver internally to execute multiple build stages in parallel, improving cache usage and potentially speeding up builds.

Cons

Complex System Requirements

Requires enabling user namespace support, installing packages like uidmap and libseccomp-dev, and ensuring sufficient /etc/subuid entries, which adds setup friction.

Limited Ecosystem Integration

Focuses only on core image operations and lacks Docker's broader tooling such as Compose or Swarm, limiting its use in full-container workflows.

Cross-platform Caveats

Native support is Linux-only; macOS and Windows users must run img inside a container, and cross-platform builds require QEMU setup for RUN commands.

Frequently Asked Questions

Related Projects

dive

A tool for exploring each layer in a docker image

Stars54,214

Forks1,990

Last commit5 months ago

kaniko

Build Container Images In Kubernetes

Stars15,765

Forks1,535

Last commit1 year ago

skopeo

Work with remote images registries - retrieving information, images, signing content

Stars10,953

Forks929

Last commit3 days ago

buildah

A tool that facilitates building OCI images.

Stars8,859

Forks901