{"id":13585713,"url":"https://github.com/dbhi/qus","last_synced_at":"2026-01-26T16:34:50.386Z","repository":{"id":39104577,"uuid":"173483243","full_name":"dbhi/qus","owner":"dbhi","description":"qemu-user-static (qus) and containers, non-invasive minimal working setups","archived":false,"fork":false,"pushed_at":"2025-01-24T00:50:42.000Z","size":3032,"stargazers_count":346,"open_issues_count":18,"forks_count":20,"subscribers_count":6,"default_branch":"main","last_synced_at":"2025-09-05T00:24:04.174Z","etag":null,"topics":["aarch64","arm32v6","arm32v7","arm64v8","binfmt","container","docker","foreign-architectures","i386","kernel","linuxkit","podman","ppc64le","qemu","qemu-user-static","register","s390x"],"latest_commit_sha":null,"homepage":"https://dbhi.github.io/qus","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/dbhi.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","license":"COPYING.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":"CITATION.cff","codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null},"funding":{"github":["umarcor"]}},"created_at":"2019-03-02T18:20:27.000Z","updated_at":"2025-08-19T00:03:03.000Z","dependencies_parsed_at":"2023-09-29T02:10:31.047Z","dependency_job_id":"8ca1380f-d131-45bc-addf-fe25eab92f89","html_url":"https://github.com/dbhi/qus","commit_stats":null,"previous_names":[],"tags_count":12,"template":false,"template_full_name":null,"purl":"pkg:github/dbhi/qus","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dbhi%2Fqus","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dbhi%2Fqus/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dbhi%2Fqus/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dbhi%2Fqus/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/dbhi","download_url":"https://codeload.github.com/dbhi/qus/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dbhi%2Fqus/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28782167,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-26T13:55:28.044Z","status":"ssl_error","status_checked_at":"2026-01-26T13:55:26.068Z","response_time":59,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"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":["aarch64","arm32v6","arm32v7","arm64v8","binfmt","container","docker","foreign-architectures","i386","kernel","linuxkit","podman","ppc64le","qemu","qemu-user-static","register","s390x"],"created_at":"2024-08-01T15:05:06.138Z","updated_at":"2026-01-26T16:34:50.366Z","avatar_url":"https://github.com/dbhi.png","language":"Python","funding_links":["https://github.com/sponsors/umarcor"],"categories":["Python"],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n  \u003ca title=\"dbhi.github.io/qus\" href=\"https://dbhi.github.io/qus\"\u003e\u003cimg src=\"./docs/_static/logo/logo_blur.png\" width=\"550\"/\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca title=\"dbhi.github.io/qus\" href=\"https://dbhi.github.io/qus\"\u003e\u003cimg src=\"https://img.shields.io/website.svg?label=dbhi.github.io%2Fqus\u0026longCache=true\u0026style=flat-square\u0026url=http%3A%2F%2Fdbhi.github.io%2Fqus%2Findex.html\"\u003e\u003c/a\u003e\u003c!--\n  --\u003e\n  \u003ca title=\"Docker Hub\" href=\"https://hub.docker.com/r/aptman/qus/\"\u003e\u003cimg src=\"https://img.shields.io/docker/pulls/aptman/qus.svg?longCache=true\u0026style=flat-square\u0026logo=docker\u0026logoColor=fff\u0026label=aptman%2Fqus\"\u003e\u003c/a\u003e\u003c!--\n  --\u003e\n  \u003ca title=\"Releases\" href=\"https://github.com/dbhi/qus/releases\"\u003e\u003cimg src=\"https://img.shields.io/github/commits-since/dbhi/qus/latest.svg?longCache=true\u0026style=flat-square\"\u003e\u003c/a\u003e\u003c!--\n  --\u003e\n  \u003ca title=\"'Test' workflow Status\" href=\"https://github.com/dbhi/qus/actions/workflows/Test.yml\"\u003e\u003cimg alt=\"'Test' workflow Status\" src=\"https://img.shields.io/github/actions/workflow/status/dbhi/qus/Test.yml?branch=main\u0026longCache=true\u0026style=flat-square\u0026logo=github\u0026label=Test\"\u003e\u003c/a\u003e\u003c!--\n  --\u003e\n  \u003ca title=\"'Canary' workflow Status\" href=\"https://github.com/dbhi/qus/actions/workflows/Canary.yml\"\u003e\u003cimg alt=\"'Canary' workflow Status\" src=\"https://img.shields.io/github/actions/workflow/status/dbhi/qus/Canary.yml?branch=main\u0026longCache=true\u0026style=flat-square\u0026logo=github\u0026label=Canary\"\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n*qemu-user-static* (**qus**) is a compilation of utilities, examples and references to build and execute OCI images (aka [docker](https://www.docker.com/) images) for foreign architectures using [QEMU](https://www.qemu.org/)'s user-mode emulation.\n\n- Ready-to-use docker images are provided for each of seven host architectures officially supported by Docker, Inc. or built by official images ([docker-library/official-images: Architectures other than amd64?](https://github.com/docker-library/official-images#architectures-other-than-amd64)): `amd64`, `i386`, `arm64v8`, `arm32v7`, `arm32v6`, `s390x` and `ppc64le`.\n- Multiple minimal working setups to build and execute `arm64v8` containers on `amd64` are configured and tested on [GitHub Actions](https://github.com/dbhi/qus/actions). The full flow is public, for other users to learn and adapt these resources to their needs.\n- These resources are tested on GNU/Linux and Windows 10 (Docker Desktop). Contributions to test them on other host OSs are welcome!\n\nFind further details at [dbhi.github.io/qus](https://dbhi.github.io/qus).\n\n# Usage\n\n\u003e NOTE: Although `docker` is used in these examples, users have reported that other engines such as [podman](https://podman.io/) can also be used. See also [kata-containers/runtime#1280](https://github.com/kata-containers/runtime/issues/1280).\n\n## As a GitHub Action\n\nRun the Action without arguments for registering all the supported interpreters:\n\n```yaml\n  - uses: dbhi/qus/action@main\n```\n\nOptionally, provide a space-separated list of target architectures:\n\n```yaml\n  - uses: dbhi/qus/action@main\n    with:\n      targets: arm aarch64\n```\n\nThen, execute foreign binaries and/or containers straightaway!\n\nNOTE: [yaml-multiline.info](https://yaml-multiline.info)\n\n## Setup\n\nThe recommended approach is to run the following container:\n\n``` bash\ndocker run --rm --privileged aptman/qus -s -- -p [TARGET_ARCH]\n```\n\n\u003e NOTE: since `aptman/qus` is a manifest, this command works on `amd64`, `arm64v8`, `arm32v7`, `arm32v6`, `i386`, `s390x` or `ppc64le` hosts.\n\nThe required `qemu-*-static` binaries (which are all included in the image) will be loaded and registered. The container will then exit. From there on, images and/or binaries for foreign architectures can be executed.\n\nOptional argument `TARGET_ARCH` is the target architecture to be translated through QEMU. If it is omitted, all available targets will be registered and loaded. The supported values are the following:\n\n```\ni386 i486 alpha arm armeb sparc32plus ppc ppc64 ppc64le m68k mips mipsel mipsn32 mipsn32el mips64 mips64el sh4 sh4eb s390x aarch64 aarch64_be hppa riscv32 riscv64 xtensa xtensaeb microblaze microblazeel or1k x86_64\n```\n\n\u003e NOTE: sudo privileges on the host are required in order to register `binfmt` formats.\n\u003e On GNU/Linux, it is possible to execute `register.sh` directly.\n\u003e On Windows, a container must be used, so that changes are applied to the underlying VM, since no kernel is available on the host\n\u003e (_i.e._, from the [test list](https://dbhi.github.io/qus/tests), only `C`, `V`, `I` or `D` will work on Windows).\n\n## Reset\n\nIn order to unset the registered formats, and unload the binaries, run:\n\n``` bash\ndocker run --rm --privileged aptman/qus -- -r\n```\n\n## Help\n\n```sh\n# docker run --rm --privileged aptman/qus -h\nUsage: register.sh [--help][--interactive][--list][--static][-- ARGS]\n\n  Wrapper around qemu-binfmt-conf.sh, to configure binfmt_misc to use qemu interpreter\n\n  -h|--help|-help:\n      display this usage\n\n  -i|--interactive|-interactive:\n      execute all the remaining args with 'sh -c', then exit\n\n  -l|--list|-list:\n      list currently registered interpreters\n\n  -s|--static|-static:\n      add '--qemu-suffix -static' to ARGS\n\n  -- ARGS:\n     arguments for qemu-binfmt-conf.sh\n\n  To register a single static target persistently, use e.g.:\n\n      register.sh -s -- -p aarch64\n\n  To remove all register interpreters and exit, use:\n\n      register.sh -- -r\n```\n\n## Bandwidth-efficient procedure\n\nIn contexts such as CI pipelines it might be desirable to reduce the required bandwidth. Hence, instead of using `aptman/qus` images —which include all the binaries for all the supported target architectures—, individual tarballs are available through GitHub Releases. These can be used along with `aptman/qus:register` images or with [`register.sh`](./register.sh) (without an OCI runtime). See either `f`, `F`, `c`, `C`, `v` or `V` in [Tests](https://dbhi.github.io/qus/tests) for examples of these use cases.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdbhi%2Fqus","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdbhi%2Fqus","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdbhi%2Fqus/lists"}