{"id":13444265,"url":"https://github.com/multiarch/qemu-user-static","last_synced_at":"2025-05-15T01:09:07.575Z","repository":{"id":37893440,"uuid":"47342812","full_name":"multiarch/qemu-user-static","owner":"multiarch","description":":earth_africa: `/usr/bin/qemu-*-static`","archived":false,"fork":false,"pushed_at":"2024-06-25T18:02:50.000Z","size":159,"stargazers_count":2562,"open_issues_count":61,"forks_count":236,"subscribers_count":40,"default_branch":"master","last_synced_at":"2025-05-13T17:19:43.956Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://hub.docker.com/r/multiarch/qemu-user-static/","language":"Shell","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/multiarch.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","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":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2015-12-03T15:59:05.000Z","updated_at":"2025-05-13T05:37:25.000Z","dependencies_parsed_at":"2023-02-10T09:35:17.083Z","dependency_job_id":"81bccff1-6fc7-4245-9569-1581235c16a6","html_url":"https://github.com/multiarch/qemu-user-static","commit_stats":null,"previous_names":[],"tags_count":49,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/multiarch%2Fqemu-user-static","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/multiarch%2Fqemu-user-static/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/multiarch%2Fqemu-user-static/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/multiarch%2Fqemu-user-static/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/multiarch","download_url":"https://codeload.github.com/multiarch/qemu-user-static/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254254042,"owners_count":22039792,"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":[],"created_at":"2024-07-31T03:02:23.286Z","updated_at":"2025-05-15T01:09:02.567Z","avatar_url":"https://github.com/multiarch.png","language":"Shell","funding_links":[],"categories":["Shell","Development Environment","others"],"sub_categories":["Build and Deploy"],"readme":"# qemu-user-static\n\n[![License](https://img.shields.io/github/license/multiarch/qemu-user-static.svg?style=flat-square)](./LICENSE) ![actions](https://github.com/multiarch/qemu-user-static/workflows/actions/badge.svg) [![Releases](https://img.shields.io/github/commits-since/multiarch/qemu-user-static/latest.svg?style=flat-square)](https://github.com/multiarch/qemu-user-static/releases) [![Docker Hub](https://img.shields.io/docker/pulls/multiarch/qemu-user-static.svg?style=flat-square)](https://hub.docker.com/r/multiarch/qemu-user-static/)\n\n![](https://raw.githubusercontent.com/multiarch/dockerfile/master/logo.jpg)\n\n**multiarch/qemu-user-static** is to enable an execution of different multi-architecture containers by QEMU [\u003csup\u003e1\u003c/sup\u003e](#ref-1) and binfmt_misc [\u003csup\u003e2\u003c/sup\u003e](#ref-2).\nHere are examples with Docker [\u003csup\u003e3\u003c/sup\u003e](#ref-3).\n\n## Getting started\n\n```\n$ uname -m\nx86_64\n\n$ docker run --rm -t arm64v8/ubuntu uname -m\nstandard_init_linux.go:211: exec user process caused \"exec format error\"\n\n$ docker run --rm --privileged multiarch/qemu-user-static --reset -p yes\n\n$ docker run --rm -t arm64v8/ubuntu uname -m\naarch64\n```\n\nIt works on many architectures and OS container images.\n\n```\n$ docker run --rm -t arm32v6/alpine uname -m\narmv7l\n\n$ docker run --rm -t ppc64le/debian uname -m\nppc64le\n\n$ docker run --rm -t s390x/ubuntu uname -m\ns390x\n\n$ docker run --rm -t arm64v8/fedora uname -m\naarch64\n\n$ docker run --rm -t arm32v7/centos uname -m\narmv7l\n\n$ docker run --rm -t ppc64le/busybox uname -m\nppc64le\n\n$ docker run --rm -t i386/ubuntu uname -m\nx86_64\n```\n\nPodman [\u003csup\u003e4\u003c/sup\u003e](#ref-4) also works.\n\n```\n$ sudo podman run --rm --privileged multiarch/qemu-user-static --reset -p yes\n\n$ podman run --rm -t arm64v8/fedora uname -m\naarch64\n```\n\nSingularity [\u003csup\u003e5\u003c/sup\u003e](#ref-5) also works.\n\n```\n$ sudo singularity run docker://multiarch/qemu-user-static --reset -p yes\n\n$ singularity run --cleanenv docker://arm64v8/fedora uname -m\naarch64\n```\n\n## Usage\n\n### multiarch/qemu-user-static images\n\nmultiarch/qemu-user-static images are managed on the [Docker Hub](https://hub.docker.com/r/multiarch/qemu-user-static/) container repository.\nThe images have below tags.\n\n**Images**\n\n1. `multiarch/qemu-user-static` image\n2. `multiarch/qemu-user-static:$version` images\n3. `multiarch/qemu-user-static:$from_arch-$to_arch` images\n4. `multiarch/qemu-user-static:$from_arch-$to_arch-$version` images\n5. `multiarch/qemu-user-static:$to_arch` images\n6. `multiarch/qemu-user-static:$to_arch-$version` images\n7. `multiarch/qemu-user-static:register` image\n\n**Variables**\n\n* `$version`: Based QEMU's version.\n* `$from_arch`: Host architecture\n* `$to_arch`: Guest architecture\n\n**Description**\n\n* `multiarch/qemu-user-static` image container includes both a register script to register binfmt_misc entries and all the `/usr/bin/qemu-$arch-static` binary files in the container in it. `multiarch/qemu-user-static` image is an alias of the latest version of `multiarch/qemu-user-static:$version` images.\n* `multiarch/qemu-user-static:$to_arch` images are aliases of `multiarch/qemu-user-static:x86_64-$to_arch`. `multiarch/qemu-user-static:$to_arch` images only include the `$to_arch`'s `/usr/bin/qemu-$to_arch-static` binary file in it. `multiarch/qemu-user-static:$to_arch` image is an alias of the latest version of `multiarch/qemu-user-static:$to_arch-$version` images.\n* `multiarch/qemu-user-static:register` image has only the register script binfmt_misc entries.\n\n`multiarch/qemu-user-static` and `multiarch/qemu-user-static:register` images execute the register script that registers below kind of `/proc/sys/fs/binfmt_misc/qemu-$arch` files for all supported processors except the current one in it when running the container. See binfmt_misc manual [2] for detail of the files.\nAs the `/proc/sys/fs/binfmt_misc` are common between host and inside of container, the register script modifies the file on host.\n\n```\n$ cat /proc/sys/fs/binfmt_misc/qemu-$arch\nenabled\ninterpreter /usr/bin/qemu-$arch-static\nflags: F\noffset 0\nmagic 7f454c460201010000000000000000000200b700\nmask ffffffffffffff00fffffffffffffffffeffffff\n```\n\nThe `--reset` option is implemented at the register script that executes `find /proc/sys/fs/binfmt_misc -type f -name 'qemu-*' -exec sh -c 'echo -1 \u003e {}' \\;` to remove binfmt_misc entry files before register the entry.\nWhen same name's file `/proc/sys/fs/binfmt_misc/qemu-$arch` exists, the register command is failed with an error message \"sh: write error: File exists\".\n\n```\n$ docker run --rm --privileged multiarch/qemu-user-static [--reset][--help][-p yes][options]\n```\n\nOn below image, we can not specify `-p yes` (`--persistent yes`) option. Because an interpreter's existance is checked when registering a binfmt_misc entry. As the interpreter does not exist in the container, the register script finishes with an error.\n\n```\n$ docker run --rm --privileged multiarch/qemu-user-static:register [--reset][--help][options]\n```\n\nThen the register script executes QEMU's [scripts/qemu-binfmt-conf.sh](https://github.com/qemu/qemu/blob/master/scripts/qemu-binfmt-conf.sh) script with options.\nYou can check `usage()` in the file about the options.\n\n```\nUsage: qemu-binfmt-conf.sh [--qemu-path PATH][--debian][--systemd CPU]\n                           [--help][--credential yes|no][--exportdir PATH]\n                           [--persistent yes|no][--qemu-suffix SUFFIX]\n       Configure binfmt_misc to use qemu interpreter\n       --help:        display this usage\n       --qemu-path:   set path to qemu interpreter ($QEMU_PATH)\n       --qemu-suffix: add a suffix to the default interpreter name\n       --debian:      don't write into /proc,\n                      instead generate update-binfmts templates\n       --systemd:     don't write into /proc,\n                      instead generate file for systemd-binfmt.service\n                      for the given CPU. If CPU is \"ALL\", generate a\n                      file for all known cpus\n       --exportdir:   define where to write configuration files\n                      (default: $SYSTEMDDIR or $DEBIANDIR)\n       --credential:  if yes, credential and security tokens are\n                      calculated according to the binary to interpret\n       --persistent:  if yes, the interpreter is loaded when binfmt is\n                      configured and remains in memory. All future uses\n                      are cloned from the open file.\n```\n\nYou can run `/usr/bin/qemu-$arch-static` binary file` in the container.\n\n```\n$ docker run --rm -t multiarch/qemu-user-static:x86_64-aarch64 /usr/bin/qemu-aarch64-static -help\nusage: qemu-aarch64 [options] program [arguments...]\nLinux CPU emulator (compiled for aarch64 emulation)\n...\n\n$ docker run --rm -t multiarch/qemu-user-static:x86_64-aarch64 /usr/bin/qemu-aarch64-static -version\nqemu-aarch64 version 4.0.0 (qemu-4.0.0-5.fc31)\nCopyright (c) 2003-2019 Fabrice Bellard and the QEMU Project developers\n\n\n$ docker run --rm -t multiarch/qemu-user-static:aarch64 /usr/bin/qemu-aarch64-static -help\nusage: qemu-aarch64 [options] program [arguments...]\nLinux CPU emulator (compiled for aarch64 emulation)\n...\n\n$ docker run --rm -t multiarch/qemu-user-static:aarch64 /usr/bin/qemu-aarch64-static -version\nqemu-aarch64 version 4.0.0 (qemu-4.0.0-5.fc31)\nCopyright (c) 2003-2019 Fabrice Bellard and the QEMU Project developers\n```\n\n`multiarch/qemu-user-static:$from_arch-$to_arch` images are used with `multiarch/qemu-user-static:register` image.\nBecause when the binfmt_misc entry is registered without `-p` option, the interpreter needs to be put in the container.\n\n```\n$ docker run --rm --privileged multiarch/qemu-user-static:register --reset\n\n$ docker build --rm -t \"test/integration/ubuntu\" -\u003c\u003cEOF\nFROM multiarch/qemu-user-static:x86_64-aarch64 as qemu\nFROM arm64v8/ubuntu\nCOPY --from=qemu /usr/bin/qemu-aarch64-static /usr/bin\nEOF\n\n$ docker run --rm -t \"test/integration/ubuntu\" uname -m\naarch64\n```\n\nIf you have `qemu-$arch-static` binary files on your local environment, you can set it to the container by `docker -v` volume mounted file.\n\n```\n$ docker run --rm --privileged multiarch/qemu-user-static:register --reset\n\n$ docker run --rm -t arm64v8/ubuntu uname -m\nstandard_init_linux.go:211: exec user process caused \"no such file or directory\"\n\n$ docker run --rm -t -v /usr/bin/qemu-aarch64-static:/usr/bin/qemu-aarch64-static arm64v8/ubuntu uname -m\naarch64\n```\n\n### multiarch compatible images [DEPRECATED]\n\nThe concept of \"compatible images\" are deprecated because **multiarch/qemu-user-static** can build and run standard multi-architecture container images without the multiarch compatible images now. But you can refer the document [Compatible images](docs/compatible_images.md).\n\nThe compatible image is the one to add `/usr/bin/qemu-$arch-static` binary inside of the container based on the standard arch specific container.\nLast time, we could not register binfmt_misc entry with `flags: F` (persistent option).\nWhen `flags: F` was not set, the interpreter always needed to be existed inside of the container to run the arch container.\n\n## Contributing\n\nWe encourage you to contribute to **multiarch/qemu-user-static**! Please check out the [Contributing to multiarch/qemu-user-static guide](CONTRIBUTING.md) for guidelines about how to proceed.\n\nSee [Developers guide](docs/developers_guide.md) for detail.\n\n## Supported host architectures\n\n* x86_64\n\nCurrently qemu-user-static is not available on other host architectures such as aarch64.\nRun `uname -m` to check it on your environment.\n\n## Examples \u0026 articles\n\nPlease note that some examples using compatible images are deprecated.\n\nSee [Examples \u0026 articles](docs/examples.md).\n\n## References\n\n* \u003ca id=\"ref-1\" href=\"#ref-1\"\u003e[1]\u003c/a\u003e QEMU: https://www.qemu.org/\n* \u003ca id=\"ref-2\" href=\"#ref-2\"\u003e[2]\u003c/a\u003e binfmt_misc: https://www.kernel.org/doc/html/latest/admin-guide/binfmt-misc.html\n* \u003ca id=\"ref-3\" href=\"#ref-3\"\u003e[3]\u003c/a\u003e Docker: https://www.docker.com/\n* \u003ca id=\"ref-4\" href=\"#ref-4\"\u003e[4]\u003c/a\u003e Podman: https://podman.io/\n* \u003ca id=\"ref-5\" href=\"#ref-5\"\u003e[5]\u003c/a\u003e Singularity: https://sylabs.io/singularity/\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmultiarch%2Fqemu-user-static","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmultiarch%2Fqemu-user-static","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmultiarch%2Fqemu-user-static/lists"}