{"id":13416454,"url":"https://github.com/genuinetools/img","last_synced_at":"2025-05-13T19:17:46.377Z","repository":{"id":37561727,"uuid":"113604197","full_name":"genuinetools/img","owner":"genuinetools","description":"Standalone, daemon-less, unprivileged Dockerfile and OCI compatible container image builder.","archived":false,"fork":false,"pushed_at":"2024-05-19T22:07:07.000Z","size":36778,"stargazers_count":3946,"open_issues_count":110,"forks_count":231,"subscribers_count":49,"default_branch":"master","last_synced_at":"2025-04-27T20:07:28.031Z","etag":null,"topics":["buildkit","cli","containers","docker","linux","opencontainers","rootless","runc"],"latest_commit_sha":null,"homepage":"https://blog.jessfraz.com/post/building-container-images-securely-on-kubernetes/","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/genuinetools.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":"AUTHORS","dei":null,"publiccode":null,"codemeta":null}},"created_at":"2017-12-08T18:17:59.000Z","updated_at":"2025-04-27T12:37:22.000Z","dependencies_parsed_at":"2024-06-18T12:27:26.086Z","dependency_job_id":"33963073-0aa6-44b3-ba1a-b968882c143c","html_url":"https://github.com/genuinetools/img","commit_stats":{"total_commits":410,"total_committers":55,"mean_commits":7.454545454545454,"dds":0.2804878048780488,"last_synced_commit":"16d3b6cad7e72f4cd9c8dad0e159902eeee00898"},"previous_names":["jessfraz/img"],"tags_count":38,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/genuinetools%2Fimg","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/genuinetools%2Fimg/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/genuinetools%2Fimg/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/genuinetools%2Fimg/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/genuinetools","download_url":"https://codeload.github.com/genuinetools/img/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254010830,"owners_count":21999004,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["buildkit","cli","containers","docker","linux","opencontainers","rootless","runc"],"created_at":"2024-07-30T21:00:59.082Z","updated_at":"2025-05-13T19:17:46.345Z","avatar_url":"https://github.com/genuinetools.png","language":"Go","readme":"# img\n\n[![make-all](https://github.com/genuinetools/img/workflows/make%20all/badge.svg)](https://github.com/genuinetools/img/actions?query=workflow%3A%22make+all%22)\n[![make-image](https://github.com/genuinetools/img/workflows/make%20image/badge.svg)](https://github.com/genuinetools/img/actions?query=workflow%3A%22make+image%22)\n[![GoDoc](https://img.shields.io/badge/godoc-reference-5272B4.svg?style=for-the-badge)](https://godoc.org/github.com/genuinetools/img)\n[![Github All Releases](https://img.shields.io/github/downloads/genuinetools/img/total.svg?style=for-the-badge)](https://github.com/genuinetools/img/releases)\n\nStandalone, daemon-less, unprivileged Dockerfile and OCI compatible\ncontainer image builder.\n\n`img` is more cache-efficient than Docker and can also execute multiple build stages concurrently, \nas it internally uses [BuildKit](https://github.com/moby/buildkit)'s DAG solver.\n\nThe commands/UX are the same as `docker {build,tag,push,pull,login,logout,save}` so all you \nhave to do is replace `docker` with `img` in your scripts, command line, and/or life.\n\n\u003c!-- START doctoc generated TOC please keep comment here to allow auto update --\u003e\n\u003c!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE --\u003e\n**Table of Contents**\n\n- [Goals](#goals)\n      - [Upstream Patches](#upstream-patches)\n      - [Benchmarks](#benchmarks)\n- [Installation](#installation)\n    - [Binaries](#binaries)\n    - [From Source](#from-source)\n    - [Alpine Linux](#alpine-linux)\n    - [Arch Linux](#arch-linux)\n    - [Gentoo](#gentoo)\n    - [Running with Docker](#running-with-docker)\n  - [Running with Kubernetes](#running-with-kubernetes)\n- [Usage](#usage)\n  - [Build an Image](#build-an-image)\n    - [Cross Platform](#cross-platform)\n    - [Exporter Types](#exporter-types)\n  - [List Image Layers](#list-image-layers)\n  - [Pull an Image](#pull-an-image)\n  - [Push an Image](#push-an-image)\n  - [Tag an Image](#tag-an-image)\n  - [Export an Image to Docker](#export-an-image-to-docker)\n  - [Unpack an Image to a rootfs](#unpack-an-image-to-a-rootfs)\n  - [Remove an Image](#remove-an-image)\n  - [Disk Usage](#disk-usage)\n  - [Prune and Cleanup the Build Cache](#prune-and-cleanup-the-build-cache)\n  - [Login to a Registry](#login-to-a-registry)\n  - [Logout from a Registry](#logout-from-a-registry)\n  - [Using Self-Signed Certs with a Registry](#using-self-signed-certs-with-a-registry)\n- [How It Works](#how-it-works)\n  - [Unprivileged Mounting](#unprivileged-mounting)\n  - [High Level](#high-level)\n  - [Low Level](#low-level)\n  - [Snapshotter Backends](#snapshotter-backends)\n    - [auto (default)](#auto-default)\n    - [native](#native)\n    - [overlayfs](#overlayfs)\n    - [fuse-overlayfs](#fuse-overlayfs)\n- [Contributing](#contributing)\n- [Acknowledgements](#acknowledgements)\n\n\u003c!-- END doctoc generated TOC please keep comment here to allow auto update --\u003e\n\n\n## Goals\n\nThis a glorified cli tool built on top of\n[buildkit](https://github.com/moby/buildkit). The goal of this project is to be\nable to build container images as an unprivileged user.\n\nRunning unprivileged allows companies who use LDAP and other login mechanisms\nto use `img` without needing root. This is very important in HPC environments\nand academia as well.\n\nCurrently this works out of the box on a Linux machine if you install via \nthe directions covered in [installing from binaries](#binaries). This\ninstallation will ensure you have the correct version of `img` and also `runc`.\n\n##### Upstream Patches\n\nThe ultimate goal is to also have this work inside a container. There are\npatches being made to container runtimes and Kubernetes to make this possible. \nFor the on-going work toward getting patches into container runtimes and\nKubernetes, see:\n\n- [moby/moby#36644](https://github.com/moby/moby/pull/36644) **merged**\n- [docker/cli#1347](https://github.com/docker/cli/pull/1347) **merged**\n- [kubernetes/community#1934](https://github.com/kubernetes/community/pull/1934) **merged**\n- [kubernetes/kubernetes#64283](https://github.com/kubernetes/kubernetes/pull/64283) **merged** \n\nThe patches for runc has been merged into the upstream since `ecd55a4135e0a26de884ce436442914f945b1e76` (May 30, 2018).\nThe upstream BuildKit can also run in rootless mode since `65b526438b86a17cf35042011051ce15c8bfb92a` (June 1, 2018).\n\nYou might also be interested in reading: \n* [the original design doc](https://docs.google.com/document/d/1rT2GUSqDGcI2e6fD5nef7amkW0VFggwhlljrKQPTn0s/edit?usp=sharing)\n* [a blog post on building images securely in Kubernetes](https://blog.jessfraz.com/post/building-container-images-securely-on-kubernetes/)\n\n##### Benchmarks\n\nIf you are curious about benchmarks comparing various container builders, check\nout [@AkihiroSuda's buildbench](https://github.com/AkihiroSuda/buildbench) \n[results](https://github.com/AkihiroSuda/buildbench/issues/1).\n\n\n## Installation\n\nYou need to have `newuidmap` installed. On Ubuntu, `newuidmap` is provided by the `uidmap` package.\n\nYou also need to have `seccomp` installed. On Ubuntu, `seccomp` is provided by the `libseccomp-dev` package.\n\n`runc` will be installed on start from an embedded binary if it is not already\navailable locally. If you would like to disable the embedded runc you can use `BUILDTAGS=\"seccomp\nnoembed\"` while building from source with `make`. Or the environment variable\n`IMG_DISABLE_EMBEDDED_RUNC=1` on execution of the `img` binary.\n\nNOTE: These steps work only for Linux. Compile and run in a container \n(explained below) if you're on Windows or MacOS.\n\n#### Binaries\n\nFor installation instructions from binaries please visit the [Releases Page](https://github.com/genuinetools/img/releases).\n\n#### From Source\n\n```bash\n$ mkdir -p $GOPATH/src/github.com/genuinetools\n$ git clone https://github.com/genuinetools/img $GOPATH/src/github.com/genuinetools/img\n$ cd !$\n$ make\n$ sudo make install\n\n# For packagers if you would like to disable the embedded `runc`, please use:\n$ make BUILDTAGS=\"seccomp noembed\"\n```\n\n#### Alpine Linux\n\nThere is an [APKBUILD](https://pkgs.alpinelinux.org/package/edge/community/x86_64/img).\n\n```console\n$ apk add img\n```\n\n#### Arch Linux\n\nThere is an [AUR build](https://aur.archlinux.org/packages/img/).\n\n```console\n# Use whichever AUR helper you prefer\n$ yay -S img\n\n# Or build from the source PKGBUILD\n$ git clone https://aur.archlinux.org/packages/img.git\n$ cd img\n$ makepkg -si\n```\n\n#### Gentoo\n\nThere is an [ebuild](https://github.com/gentoo/gentoo/tree/master/app-emulation/img).\n\n```console\n$ sudo emerge -a app-emulation/img\n```\n\n#### Running with Docker\n\nDocker image `r.j3ss.co/img` is configured to be executed as an unprivileged user with UID 1000 and it does not need `--privileged` since `img` v0.5.11.\n\n```console\n$ docker run --rm -it \\\n    --name img \\\n    --volume $(pwd):/home/user/src:ro \\ # for the build context and dockerfile, can be read-only since we won't modify it\n    --workdir /home/user/src \\ # set the builder working directory\n    --volume \"${HOME}/.docker:/root/.docker:ro\" \\ # for credentials to push to docker hub or a registry\n    --security-opt seccomp=unconfined --security-opt apparmor=unconfined \\ # required by runc\n    r.j3ss.co/img build -t user/myimage .\n```\n\nTo enable PID namespace isolation (which disallows build containers to `kill(2)` the `img` process), you need to specify\n`--privileged` so that build containers can mount `/proc` with unshared PID namespaces.\nNote that even with `--privileged`, `img` works as an unprivileged user with UID 1000.\n\nSee [docker/cli patch](#upstream-patches) for how to allow mounting `/proc` without `--privileged`.\n\n### Running with Kubernetes\n\nSince `img` v0.5.11, you don't need to specify any `securityContext` for running `img` as a Kubernetes container.\n\nHowever the following security annotations are needed:\n```\ncontainer.apparmor.security.beta.kubernetes.io/img: unconfined\ncontainer.seccomp.security.alpha.kubernetes.io/img: unconfined\n```\n\nTo enable PID namespace isolation, you need to set `securityContext.procMount` to `Unmasked` (or simply set\n`securityContext.privileged` to `true`).\n`securityContext.procMount` is available since Kubernetes 1.12 with Docker 18.06/containerd 1.2/CRI-O 1.12.\n\n## Usage\n\nMake sure you have user namespace support enabled. On some distros (Debian and\nArch Linux) this requires running `echo 1 \u003e /proc/sys/kernel/unprivileged_userns_clone`.\n\n\n```console\n$ img -h\nimg -  Standalone, daemon-less, unprivileged Dockerfile and OCI compatible container image builder\n\nUsage: img [OPTIONS] COMMAND [ARG...]\n\nFlags:\n  -b, --backend string   backend for snapshots ([auto native overlayfs fuse-overlayfs]) (default \"auto\")\n  -d, --debug            enable debug logging\n  -h, --help             help for img\n  -s, --state string     directory to hold the global state (default \"/home/user/.local/share/img\")\n  -v, --version          Print version information and quit\n\nCommands:\n  build       Build an image from a Dockerfile\n  du          Show image disk usage.\n  help        Help about any command\n  login       Log in to a Docker registry.\n  logout      Log out from a Docker registry.\n  ls          List images and digests.\n  prune       Prune and clean up the build cache.\n  pull        Pull an image or a repository from a registry.\n  push        Push an image or a repository to a registry.\n  rm          Remove one or more images.\n  save        Save an image to a tar archive (streamed to STDOUT by default).\n  tag         Create a tag TARGET_IMAGE that refers to SOURCE_IMAGE.\n  unpack      Unpack an image to a rootfs directory.\n  version     Show the version information.\n\nUse \"img [command] --help\" for more information about a command.\n```\n\n### Build an Image\n\n```console\n$ img build -h\nbuild -  Build an image from a Dockerfile\n\nUsage: img build [OPTIONS] PATH\n\nFlags:\n      --build-arg list    Set build-time variables\n      --cache-from list   Buildkit import-cache or Buildx cache-from specification\n      --cache-to list     Buildx cache-to specification\n  -f, --file string       Name of the Dockerfile (Default is 'PATH/Dockerfile')\n  -h, --help              help for build\n      --label list        Set metadata for an image\n      --no-cache          Do not use cache when building the image\n      --no-console        Use non-console progress UI\n  -o, --output string     BuildKit output specification (e.g. type=tar,dest=build.tar)\n      --platform list     Set platforms for which the image should be built\n  -t, --tag list          Name and optionally a tag in the 'name:tag' format\n      --target string     Set the target build stage to build\n\nGlobal Flags:\n  -b, --backend string   backend for snapshots ([auto native overlayfs fuse-overlayfs]) (default \"auto\")\n  -d, --debug            enable debug logging\n  -s, --state string     directory to hold the global state (default \"/home/user/.local/share/img\")\n```\n\n**Use just like you would `docker build`.**\n\n```console\n$ img build -t r.j3ss.co/img .\nBuilding r.j3ss.co/img:latest\nSetting up the rootfs... this may take a bit.\n[+] Building 44.7s (16/16) FINISHED                                                        \n =\u003e local://dockerfile (Dockerfile)                                                   0.0s\n =\u003e =\u003e transferring dockerfile: 1.15kB                                                0.0s\n =\u003e local://context (.dockerignore)                                                   0.0s\n =\u003e =\u003e transferring context: 02B                                                      0.0s\n =\u003e CACHED docker-image://docker.io/tonistiigi/copy:v0.1.1@sha256:854cee92ccab4c6d63  0.0s\n =\u003e =\u003e resolve docker.io/tonistiigi/copy:v0.1.1@sha256:854cee92ccab4c6d63183d147389e  0.0s\n =\u003e CACHED docker-image://docker.io/library/alpine@sha256:e1871801d30885a610511c867d  0.0s\n =\u003e =\u003e resolve docker.io/library/alpine@sha256:e1871801d30885a610511c867de0d6baca7ed  0.0s\n =\u003e docker-image://docker.io/library/golang:1.10-alpine@sha256:98c1f3458b21f50ac2e58  5.5s\n =\u003e =\u003e resolve docker.io/library/golang:1.10-alpine@sha256:98c1f3458b21f50ac2e5896d1  0.0s\n =\u003e =\u003e sha256:866414f805391b58973d4e3d76e5d32ae51baecb1c93762c9751b9d6c5 126B / 126B  0.0s\n =\u003e =\u003e sha256:ae8dbf6f23bf1c326de78fc780c6a870bf11eb86b45a7dc567 308.02kB / 308.02kB  0.0s\n =\u003e =\u003e sha256:44ccce322b34208317d748e998212cd677c16f1a58c2ff5e59578c 3.86kB / 3.86kB  0.0s\n =\u003e =\u003e sha256:0d01df27c53e651ecfa5c689dafb8c63c759761a757cc37e30eccc5e3a 153B / 153B  0.0s\n =\u003e =\u003e sha256:ff3a5c916c92643ff77519ffa742d3ec61b7f591b6b7504599d95a 2.07MB / 2.07MB  0.0s\n =\u003e =\u003e sha256:4be696a8d726150ed9636ea7156edcaa9ba8293df1aae49f9e 113.26MB / 113.26MB  0.0s\n =\u003e =\u003e sha256:98c1f3458b21f50ac2e5896d14a644eadb3adcae5afdceac0cc9c2 2.04kB / 2.04kB  0.0s\n =\u003e =\u003e sha256:bb31085d5c5db578edf3d4e5541cfb949b713bb7018bbac4dfd407 1.36kB / 1.36kB  0.0s\n =\u003e =\u003e unpacking docker.io/library/golang:1.10-alpine@sha256:98c1f3458b21f50ac2e5896  5.4s\n =\u003e local://context                                                                   0.8s\n =\u003e =\u003e transferring context: 116.83MB                                                 0.8s\n =\u003e /bin/sh -c apk add --no-cache  bash  build-base  gcc  git  libseccomp-dev  linux  3.8s\n =\u003e copy /src-0 go/src/github.com/genuinetools/img/                                   1.5s\n =\u003e /bin/sh -c go get -u github.com/jteeuwen/go-bindata/...                           7.3s\n =\u003e /bin/sh -c make static \u0026\u0026 mv img /usr/bin/img                                    15.2s\n =\u003e /bin/sh -c git clone https://github.com/opencontainers/runc.git \"$GOPATH/src/git  7.6s\n =\u003e /bin/sh -c apk add --no-cache  bash  git  shadow  shadow-uidmap  strace           2.3s\n =\u003e copy /src-0/img usr/bin/img                                                       0.5s\n =\u003e copy /src-0/runc usr/bin/runc                                                     0.4s\n =\u003e /bin/sh -c useradd --create-home --home-dir $HOME user  \u0026\u0026 chown -R user:user $H  0.4s\n =\u003e exporting to image                                                                1.5s\n =\u003e =\u003e exporting layers                                                               1.4s\n =\u003e =\u003e exporting manifest sha256:03e034afb839fe6399a271efc972da823b1b6297ea792ec94fa  0.0s\n =\u003e =\u003e exporting config sha256:92d033f9575176046db41f4f1feacc0602c8f2811f59d59f8e7b6  0.0s\n =\u003e =\u003e naming to r.j3ss.co/img:latest                                                 0.0s\nSuccessfully built r.j3ss.co/img:latest\n```\n\n#### Cross Platform\n\n`img` and the underlying `buildkit` library support building containers for arbitrary platforms (OS and architecture combinations). In `img` this can be achieved using the `--platform` option, but note that\nusing the `RUN` command during a build requires installing support for the desired platform, and any `FROM` images used must exist for the target platform as well.\n\nSome common platforms include:\n* linux/amd64\n* linux/arm64\n* linux/arm/v7\n* linux/arm/v6\n* linux/s390x\n* linux/ppc64le\n* darwin/amd64\n* windows/amd64\n\nIf you use multiple `--platform` options for the same build, they will be included into a [manifest](https://docs.docker.com/engine/reference/commandline/manifest/) and should work for the different platforms built for.\n\nThe most common way to get `RUN` working in cross-platform builds is to install an emulator such as QEMU on the host system (static bindings are recommended to avoid shared library loading issues). To properly use the emulator inside the build environment, the kernel [binfmt_misc](https://www.kernel.org/doc/html/latest/admin-guide/binfmt-misc.html) parameters must be set with the following flags: `OCF`.\nYou can check the settings in `/proc` to ensure they are set correctly.\n```console\n$ cat /proc/sys/fs/binfmt_misc/qemu-arm | grep flags\nflags: OCF\n```\n\nOn Debian/Ubuntu the above should be available with the `qemu-user-static` package \u003e= `1:2.12+dfsg-3`\n\nNOTE: cross-OS builds are slightly more complicated to get `RUN` commands working, but follow from the same principle.\n\n#### Exporter Types\n\n[bkoutputs]: https://github.com/moby/buildkit/blob/master/README.md#output\n\n`img` can also use buildkit's [exporter types][bkoutputs] directly to output the\nresulting image to a Docker-type bundle or a rootfs tar without saving the image\nitself locally. Builds will still benefit from caching.\n\nThe output type and destination are specified with the `--output` flag. The list\nof valid output specifications includes:\n\n| flag | description |\n|------------|-------------|\n| `-o type=tar,dest=rootfs.tar` | export rootfs of target image to a tar archive |\n| `-o type=tar` | output a rootfs tar to stdout, for use in piped commands |\n| `-o type=docker,dest=image.tar` | save a Docker-type bundle of the image |\n| `-o type=oci,dest=image.tar` | save an OCI-type bundle of the image |\n| `-o type=local,dest=rootfs/` | export the target image to this directory |\n| `-o type=image,name=r.j3ss.co/img` | build and tag an image and store it locally\n\nWhen used in conjunction with a Dockerfile which has a final `FROM scratch` stage and\nonly copies files of interest from earlier stages with `COPY --from=...`, this can be\nutilized to output arbitrary build artifacts for example.\n\n### List Image Layers\n\n```console\n$ img ls -h\nls -  List images and digests.\n\nUsage: img ls [OPTIONS]\n\nFlags:\n  -f, --filter list   Filter output based on conditions provided\n  -h, --help          help for ls\n\nGlobal Flags:\n  -b, --backend string   backend for snapshots ([auto native overlayfs fuse-overlayfs]) (default \"auto\")\n  -d, --debug            enable debug logging\n  -s, --state string     directory to hold the global state (default \"/home/user/.local/share/img\")\n```\n\n```console\n$ img ls\nNAME                    SIZE            CREATED AT      UPDATED AT      DIGEST\njess/img:latest         1.534KiB        9 seconds ago   9 seconds ago   sha256:27d862ac32022946d61afbb91ddfc6a1fa2341a78a0da11ff9595a85f651d51e\njess/thing:latest       591B            30 minutes ago  30 minutes ago  sha256:d664b4e9b9cd8b3067e122ef68180e95dd4494fd4cb01d05632b6e77ce19118e\n```\n\n### Pull an Image\n\nIf you need to use self-signed certs with your registry, see \n[Using Self-Signed Certs with a Registry](#using-self-signed-certs-with-a-registry).\n\n```console\n$ img pull -h\npull -  Pull an image or a repository from a registry.\n\nUsage: img pull [OPTIONS] NAME[:TAG|@DIGEST]\n\nFlags:\n  -h, --help   help for pull\n\nGlobal Flags:\n  -b, --backend string   backend for snapshots ([auto native overlayfs fuse-overlayfs]) (default \"auto\")\n  -d, --debug            enable debug logging\n  -s, --state string     directory to hold the global state (default \"/home/user/.local/share/img\")\n```\n\n```console\n$ img pull r.j3ss.co/stress\nPulling r.j3ss.co/stress:latest...\nSnapshot ref: sha256:2bb7a0a5f074ffe898b1ef64b3761e7f5062c3bdfe9947960e6db48a998ae1d6\nSize: 365.9KiB\n```\n\n### Push an Image\n\nIf you need to use self-signed certs with your registry, see \n[Using Self-Signed Certs with a Registry](#using-self-signed-certs-with-a-registry).\n\n```console\n$ img push -h\npush -  Push an image or a repository to a registry.\n\nUsage: img push [OPTIONS] NAME[:TAG]\n\nFlags:\n  -h, --help                help for push\n      --insecure-registry   Push to insecure registry\n\nGlobal Flags:\n  -b, --backend string   backend for snapshots ([auto native overlayfs fuse-overlayfs]) (default \"auto\")\n  -d, --debug            enable debug logging\n  -s, --state string     directory to hold the global state (default \"/home/user/.local/share/img\")\n```\n\n```console\n$ img push jess/thing\nPushing jess/thing:latest...\nSuccessfully pushed jess/thing:latest\n```\n\n### Tag an Image\n\n```console\n$ img tag -h\ntag -  Create a tag TARGET_IMAGE that refers to SOURCE_IMAGE.\n\nUsage: img tag SOURCE_IMAGE[:TAG] TARGET_IMAGE[:TAG]\n\nFlags:\n  -h, --help   help for tag\n\nGlobal Flags:\n  -b, --backend string   backend for snapshots ([auto native overlayfs fuse-overlayfs]) (default \"auto\")\n  -d, --debug            enable debug logging\n  -s, --state string     directory to hold the global state (default \"/home/user/.local/share/img\")\n```\n\n```console\n$ img tag jess/thing jess/otherthing\nSuccessfully tagged jess/thing as jess/otherthing\n```\n\n### Export an Image to Docker\n\n```console\n$ img save -h\nsave -  Save an image to a tar archive (streamed to STDOUT by default).\n\nUsage: img save [OPTIONS] IMAGE [IMAGE...]\n\nFlags:\n      --format string   image output format (docker|oci) (default \"docker\")\n  -h, --help            help for save\n  -o, --output string   write to a file, instead of STDOUT\n\nGlobal Flags:\n  -b, --backend string   backend for snapshots ([auto native overlayfs fuse-overlayfs]) (default \"auto\")\n  -d, --debug            enable debug logging\n  -s, --state string     directory to hold the global state (default \"/home/user/.local/share/img\")\n```\n\n```console\n$ img save jess/thing | docker load\n6c3d70c8619c: Loading layer [==================================================\u003e]  9.927MB/9.927MB                                      \n7e336c441b5e: Loading layer [==================================================\u003e]  5.287MB/5.287MB                                      \n533fecff21a8: Loading layer [==================================================\u003e]   2.56MB/2.56MB                                       \n3db7019eac28: Loading layer [==================================================\u003e]  1.679kB/1.679kB                                      \nLoaded image: jess/thing\n```\n\n### Unpack an Image to a rootfs\n\n```console\n$ img unpack -h\nunpack -  Unpack an image to a rootfs directory.\n\nUsage: img unpack [OPTIONS] IMAGE\n\nFlags:\n  -h, --help            help for unpack\n  -o, --output string   Directory to unpack the rootfs to. (defaults to rootfs/ in the current working directory)\n\nGlobal Flags:\n  -b, --backend string   backend for snapshots ([auto native overlayfs fuse-overlayfs]) (default \"auto\")\n  -d, --debug            enable debug logging\n  -s, --state string     directory to hold the global state (default \"/home/user/.local/share/img\")\n```\n\n```console\n$ img unpack busybox\nSuccessfully unpacked rootfs for busybox to: /home/user/rootfs\n```\n\n### Remove an Image\n\n```console\n$ img rm -h\nrm -  Remove one or more images.\n\nUsage: img rm [OPTIONS] IMAGE [IMAGE...]\n\nFlags:\n  -h, --help   help for rm\n\nGlobal Flags:\n  -b, --backend string   backend for snapshots ([auto native overlayfs fuse-overlayfs]) (default \"auto\")\n  -d, --debug            enable debug logging\n  -s, --state string     directory to hold the global state (default \"/home/user/.local/share/img\")\n```\n\n### Disk Usage\n\n```console\n$ img du -h\ndu -  Show image disk usage.\n\nUsage: img du [OPTIONS]\n\nFlags:\n  -f, --filter list   Filter output based on conditions provided\n  -h, --help          help for du\n\nGlobal Flags:\n  -b, --backend string   backend for snapshots ([auto native overlayfs fuse-overlayfs]) (default \"auto\")\n  -d, --debug            enable debug logging\n  -s, --state string     directory to hold the global state (default \"/home/user/.local/share/img\")\n```\n\n```console\n$ img du \nID                                                                      RECLAIMABLE     SIZE            DESCRIPTION\nsha256:d9a48086f223d28a838263a6c04705c8009fab1dd67cc82c0ee821545de3bf7c true            911.8KiB        pulled from docker.io/tonistiigi/copy@sha256:476e0a67a1e4650c6adaf213269a2913deb7c52cbc77f954026f769d51e1a14e\n7ia86xm2e4hzn2u947iqh9ph2                                               true            203.2MiB        mount /dest from exec copy /src-0 /dest/go/src/github.com/genuinetools/img\n...\nsha256:9f131fba0383a6aaf25ecd78bd5f37003e41a4385d7f38c3b0cde352ad7676da true            958.6KiB        pulled from docker.io/library/golang:alpine@sha256:a0045fbb52a7ef318937e84cf7ad3301b4d2ba6cecc2d01804f428a1e39d1dfc\nsha256:c4151b5a5de5b7e272b2b6a3a4518c980d6e7f580f39c85370330a1bff5821f1 true            472.3KiB        pulled from docker.io/tonistiigi/copy@sha256:476e0a67a1e4650c6adaf213269a2913deb7c52cbc77f954026f769d51e1a14e\nsha256:ae4ecac23119cc920f9e44847334815d32bdf82f6678069d8a8be103c1ee2891 true            148.9MiB        pulled from docker.io/library/debian:buster@sha256:a7789365b226786a0cb9e0f142c515f9f2ede7164a6f6be4a1dc4bfe19d5ec9c\nbkrjrzv3nvp7lvzd5cw9vzut7*                                              true            4.879KiB        local source for dockerfile\nsha256:db193011cbfc238d622d65c4099750758df83d74571e8d7498392b17df381207 true            467.2MiB        pulled from docker.io/library/golang:alpine@sha256:a0045fbb52a7ef318937e84cf7ad3301b4d2ba6cecc2d01804f428a1e39d1dfc\nwn4m5i5swdcjvt1ud5bvtr75h*                                              true            4.204KiB        local source for dockerfile\nReclaimable:    1.08GiB\nTotal:          1.08GiB\n```\n\n### Prune and Cleanup the Build Cache\n\n```console\n$ img prune -h\nprune -  Prune and clean up the build cache.\n\nUsage: img prune [OPTIONS]\n\nFlags:\n  -h, --help   help for prune\n\nGlobal Flags:\n  -b, --backend string   backend for snapshots ([auto native overlayfs fuse-overlayfs]) (default \"auto\")\n  -d, --debug            enable debug logging\n  -s, --state string     directory to hold the global state (default \"/home/user/.local/share/img\")\n```\n\n```console\n$ img prune\nID                                                                      RECLAIMABLE     SIZE            DESCRIPTION\nj1yil8bdz35eyxp0m17tggknd                                               true            5.08KiB         local source for dockerfile\nje23wfyz2apii1au38occ8zag                                               true            52.95MiB        mount / from exec /bin/sh -c useradd --create-home...\nsha256:74906c0186257f2897c5fba99e1ea87eb8b2ee0bb03b611f5e866232bfbf6739 true            2.238MiB        pulled from docker.io/tonistiigi/copy:v0.1.1@sha25...\nvr2pvhmrt1sjs8n7jodesrvnz*                                              true            572.6MiB        mount / from exec /bin/sh -c git clone https://git...\nafn0clz11yphlv6g8golv59c8                                               true            4KiB            local source for context\nqx5yql370piuscuczutrnansv*                                              true            692.4MiB        mount / from exec /bin/sh -c make static \u0026\u0026 mv img...\nuxocruvniojl1jqlm8gs3ds1e*                                              true            113.8MiB        local source for context\nsha256:0b9cfed6a170b357c528cd9dfc104d8b404d08d84152b38e98c60f50d2ae718b true            1.449MiB        pulled from docker.io/tonistiigi/copy:v0.1.1@sha25...\nvz0716utmnlmya1vhkojyxd4o                                               true            55.39MiB        mount /dest from exec copy /src-0/runc usr/bin/run...\na0om6hwulbf9gd2jfgmxsyaoa                                               true            646.5MiB        mount / from exec /bin/sh -c go get -u github.com/...\nys8y9ixi3didtbpvwbxuptdfq                                               true            641.2MiB        mount /dest from exec copy /src-0 go/src/github.co...\nsha256:f64a552a56ce93b6e389328602f2cd830280fd543ade026905e69895b5696b7a true            1.234MiB        pulled from docker.io/tonistiigi/copy:v0.1.1@sha25...\n05wxxnq6yu5nssn3bojsz2mii                                               true            52.4MiB         mount /dest from exec copy /src-0/img usr/bin/img\nwlrp1nxsa37cixf127bh6w2sv                                               true            35.11MiB        mount / from exec /bin/sh -c apk add --no-cache  b...\nwy0173xa6rkoq49tf9g092r4z                                               true            527.4MiB        mount / from exec /bin/sh -c apk add --no-cache  b...\nReclaimed:      4.148GiB\nTotal:          4.148GiB\n```\n\n### Login to a Registry\n\nIf you need to use self-signed certs with your registry, see \n[Using Self-Signed Certs with a Registry](#using-self-signed-certs-with-a-registry).\n\n```console\n$ img login -h\nlogin -  Log in to a Docker registry.\n\nUsage: img login [OPTIONS] [SERVER]\n\nFlags:\n  -h, --help              help for login\n  -p, --password string   Password\n      --password-stdin    Take the password from stdin\n  -u, --username string   Username\n\nGlobal Flags:\n  -b, --backend string   backend for snapshots ([auto native overlayfs fuse-overlayfs]) (default \"auto\")\n  -d, --debug            enable debug logging\n  -s, --state string     directory to hold the global state (default \"/home/user/.local/share/img\")\n```\n\n### Logout from a Registry\n\n```console\n$ img logout -h\nlogout -  Log out from a Docker registry.\n\nUsage: img logout [SERVER]\n\nFlags:\n  -h, --help   help for logout\n\nGlobal Flags:\n  -b, --backend string   backend for snapshots ([auto native overlayfs fuse-overlayfs]) (default \"auto\")\n  -d, --debug            enable debug logging\n  -s, --state string     directory to hold the global state (default \"/home/user/.local/share/img\")\n```\n\n### Using Self-Signed Certs with a Registry\n\nWe do not allow users to pass all the custom certificate flags on commands\nbecause it is unnecessarily messy and can be handled through Linux itself.\nWhich we believe is a better user experience than having to pass three\ndifferent flags just to communicate with a registry using self-signed or\nprivate certificates.\n\nBelow are instructions on adding a self-signed or private certificate to your\ntrusted ca-certificates on Linux.\n\nMake sure you have the package `ca-certificates` installed.\n\nCopy the public half of your CA certificate (the one user to sign the CSR) into\nthe CA certificate directory (as root):\n\n```console\n$ cp cacert.pem /usr/share/ca-certificates\n```\n\nRebuild the directory with your certificate included, run as root:\n\n```console\n# On debian, this will bring up a menu.\n# Select the ask option, scroll to the certificate you are adding,\n# \tmark it for inclusion, and select ok.\n$ dpkg-reconfigure ca-certificates\n\n# On other distros...\n$ update-ca-certificates\n```\n\n## How It Works\n\n### Unprivileged Mounting\n\nTo mount a filesystem without root accsess, `img` automatically invokes \n[`newuidmap(1)`](http://man7.org/linux/man-pages/man1/newuidmap.1.html)/[`newgidmap(1)`](http://man7.org/linux/man-pages/man1/newgidmap.1.html) \nSUID binaries to prepare SUBUIDs/SUBGIDs, which is typically required by `apt`.\n\nMake sure you have sufficient entries (typically `\u003e=65536`) in your \n`/etc/subuid` and `/etc/subgid`.\n\n### High Level\n\n\u003cimg src=\"contrib/how-it-works-high-level.png\" width=300 /\u003e\n\n### Low Level\n\n\u003cimg src=\"contrib/how-it-works-low-level.png\" width=300 /\u003e\n\n### Snapshotter Backends\n\n#### auto (default)\n\nThe `auto` backend selects a backend based on what the current system supports,\npreferring `overlayfs`, then `fuse-overlayfs`, then `native`.\n\n#### native\n\nThe `native` backend creates image layers by simply copying files.\n`copy_file_range(2)` is used when available.\n\n#### overlayfs\n\nThe `overlayfs` backend uses the kernel's native overlayfs support. It requires\na kernel patch from Ubuntu to be unprivileged, see\n[#22](https://github.com/genuinetools/img/issues/22).\n\n#### fuse-overlayfs\n\nThe `fuse-overlayfs` backend provides overlay support without any kernel\npatches. It requires a Linux kernel \u003e= 4.18 and for\n[fuse-overlayfs](https://github.com/containers/fuse-overlayfs) to be installed.\n\n\n## Contributing\n\nPlease do! This is a new project and can use some love \u003c3. Check out the [issues](https://github.com/genuinetools/img/issues).\n\nThe local directories are mostly re-implementations of `buildkit` interfaces to\nbe unprivileged.\n\n## Acknowledgements\n\nA lot of this is based on the work of [moby/buildkit](https://github.com/moby/buildkit). \nThanks [@tonistiigi](https://github.com/tonistiigi) and\n[@AkihiroSuda](https://github.com/AkihiroSuda)!\n","funding_links":[],"categories":["Go","Docker Images","Runtimes \u0026 Platforms","cli","runc","Virtualization"],"sub_categories":["Builder","Containers"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgenuinetools%2Fimg","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgenuinetools%2Fimg","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgenuinetools%2Fimg/lists"}