{"id":14235877,"url":"https://github.com/singularityhub/docker2singularity","last_synced_at":"2025-09-03T17:37:48.481Z","repository":{"id":38799945,"uuid":"65048344","full_name":"singularityhub/docker2singularity","owner":"singularityhub","description":"A docker image for converting docker images to singularity images.","archived":false,"fork":false,"pushed_at":"2024-07-30T05:22:28.000Z","size":309,"stargazers_count":287,"open_issues_count":9,"forks_count":35,"subscribers_count":8,"default_branch":"master","last_synced_at":"2025-03-29T20:05:33.177Z","etag":null,"topics":["docker","docker-image","singularity","singularity-images"],"latest_commit_sha":null,"homepage":"https://quay.io/repository/singularity/docker2singularity?tab=tags","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/singularityhub.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":".github/CONTRIBUTING.md","funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":".github/CODE_OF_CONDUCT.md","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},"funding":{"github":"vsoch"}},"created_at":"2016-08-05T20:53:24.000Z","updated_at":"2025-03-21T17:01:42.000Z","dependencies_parsed_at":"2023-01-22T02:31:55.357Z","dependency_job_id":"9a8408d4-22b8-49fd-9566-1ccdee668c05","html_url":"https://github.com/singularityhub/docker2singularity","commit_stats":null,"previous_names":[],"tags_count":4,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/singularityhub%2Fdocker2singularity","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/singularityhub%2Fdocker2singularity/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/singularityhub%2Fdocker2singularity/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/singularityhub%2Fdocker2singularity/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/singularityhub","download_url":"https://codeload.github.com/singularityhub/docker2singularity/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247399877,"owners_count":20932876,"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":["docker","docker-image","singularity","singularity-images"],"created_at":"2024-08-20T21:02:27.452Z","updated_at":"2025-04-05T21:08:45.722Z","avatar_url":"https://github.com/singularityhub.png","language":"Shell","readme":"# `docker2singularity`\n\n\u003cimg src=\"img/logo.png\" alt=\"https://www.sylabs.io/guides/latest/user-guide\" data-canonical-src=\"https://www.sylabs.io/guides/latest/user-guide\" width=\"200\" height=\"200\"\u003e\n\n[![CircleCI](https://circleci.com/gh/singularityhub/docker2singularity.svg?style=svg)](https://circleci.com/gh/singularityhub/docker2singularity)\n\nAre you developing Docker images and you would like to run them on an HPC cluster \nsupporting [Singularity](https://www.sylabs.io/guides/latest/user-guide/)? \nAre you working on Mac or Windows with no easy access to a Linux machine? If the pull, \nbuild, and general commands to work with docker images provided by Singularity\nnatively do not fit your needs, `docker2singularity` is an alternative way to generate Singularity images. \nThe containers are available to you on [quay.io](https://quay.io/repository/singularity/docker2singularity),\nand older versions also available for you on [Docker Hub](https://hub.docker.com/r/singularityware/docker2singularity/).\n\n## Usage\n\n```bash\n$ docker run quay.io/singularity/docker2singularity\nUSAGE: docker2singularity [-m \"/mount_point1 /mount_point2\"] [options] docker_image_name\nOPTIONS:\n\n          Image Format\n              --folder   -f   build development sandbox (folder)\n              --option   -o   add a custom option to build (-o --fakeroot or -option 'section post' )\n              --writable -w   non-production writable image (ext3)         \n                              Default is squashfs (recommended) (deprecated)\n              --name     -n   provide basename for the container (default based on URI)\n              --mount    -m   provide list of custom mount points (in quotes!)\n              --help     -h   show this help and exit\n```\n\n### Options\n\n**Image Format**\n\n - `squashfs` (no arguments specified) gives you a squashfs (`*.simg`) image. This is a compressed, reliable, and read only format that is recommended for production images. Squashfs support was added to Singularity proper in [January of 2017](https://github.com/sylabs/singularity/commit/0cf00d1251ff276d5b9b7a0e4eadb783a45a6b65#diff-8405d9d311d83f009adff55c3deb112c) and thus available as early as the 2.2.1 release.\n - `sandbox` (`-f`) builds your image into a sandbox **folder**. This is ideal for development, as it will produce a working image in a folder on your system.\n - `ext3` (`-w`) builds an older format (ext3) image (`*.img`). This format is not recommended for production images as we have observed degradation of the images over time, and they tend to be upwards of 1.5x to 2x the size of squashfs.\n\nNote that you are able to convert easily from a folder or ext3 image using Singularity 2.4. If your choice is to develop, making changes, and then finalize, this approach is **not** recommended - your changes are not recorded and thus the image not reproducible.\n\n**Mount Points**\n\n - `-m` specify one or more mount points to create in the image.\n\n**Options**\n\nIf you look at `singularity build --help` there are a variety of options available.\nYou can specify some custom option to the command using the `--option` flag. Make sure\nthat each option that you specify is captured as a single string. E.g.,:\n\n```bash\n--option --fakeroot \n--option '--section post'\n```\n\n**Image Name**\n\nThe last argument (without a letter) is the name of the docker image, as you would specify to run with Docker (e.g., `docker run ubuntu:latest`)\n\n\n## Legacy\n\nIf you want a legacy version, see the [repository branches](https://github.com/singularityhub/docker2singularity/branches)\nand [tag history](https://quay.io/repository/singularity/docker2singularity?tab=tags\u0026tag=latest) on the registry.\n\nContainers were previous built on [Docker Hub](https://hub.docker.com/r/singularityware/docker2singularity/tags/) and\nnow are provided on [quay.io](https://quay.io/repository/singularity/docker2singularity?tab=tags). A tag with prefix `v` corresponds to a release of the Singularity software, while the others are in reference to releases of Docker. Previously used [scripts](https://github.com/singularityhub/docker2singularity/tree/master/scripts), including environment and action files, are provided in this repository for reference.\n\n## Requirements\n\n - Docker (native Linux or Docker for Mac or Docker for Windows) - to create the Singularity image.\n - Singularity \u003e= 2.1 - to run the Singularity image (**versions 2.0 and older are not supported!**). Note that if running a 2.4 image using earlier versions, not all (later developed) features may be available.\n\n## Examples\n\n### Build a Squashfs Image\n\nSquashfs is the recommended image type, it is compressed and less prone to degradation over time. You don't need to specify anything special to create it:\n\nThis is a path on my host, the image will be written here\n\n```bash\n$ mkdir -p /tmp/test\n```\n\nAnd here is the command to run. Notice that I am mounting the path `/tmp/test` that I created above to `/output` in the container, where the container image will be written (and seen on my host).\n\n```bash\n$ docker run -v /var/run/docker.sock:/var/run/docker.sock \\\n-v /tmp/test:/output \\\n--privileged -t --rm \\\nquay.io/singularity/docker2singularity \\\nubuntu:14.04\n\nImage Format: squashfs\nInspected Size: 188 MB\n\n(1/10) Creating a build sandbox...\n(2/10) Exporting filesystem...\n(3/10) Creating labels...\n(4/10) Adding run script...\n(5/10) Setting ENV variables...\n(6/10) Adding mount points...\n(7/10) Fixing permissions...\n(8/10) Stopping and removing the container...\n(9/10) Building squashfs container...\nBuilding image from sandbox: /tmp/ubuntu_14.04-2017-09-13-3e51deeadc7b.build\nBuilding Singularity image...\nSingularity container built: /tmp/ubuntu_14.04-2017-09-13-3e51deeadc7b.simg\nCleaning up...\n(10/10) Moving the image to the output folder...\n     62,591,007 100%  340.92MB/s    0:00:00 (xfr#1, to-chk=0/1)\nFinal Size: 60MB\n```\n\nWe can now see the finished image!\n\n```bash\n$ ls /tmp/test\nubuntu_14.04-2018-04-27-c7e04ea7fa32.simg\n```\n\nAnd use it!\n\n```bash\n$ singularity shell /tmp/test/ubuntu_14.04-2018-04-27-c7e04ea7fa32.simg\nSingularity: Invoking an interactive shell within container...\n\nSingularity ubuntu_14.04-2018-04-27-c7e04ea7fa32.simg:~/Documents/Dropbox/Code/singularity/docker2singularity\u003e \n```\n\nTake a look again at the generation code above, and notice how the image went from 188MB to 60MB? \nThis is one of the great things about the squashfs filesystem! This reduction is even more impressive when we are dealing with very large images (e.g., ~3600 down to ~1800). A few notes on the inputs shown above that you should edit:\n\n - `/tmp/test`: the path you want to have the final image reside. If you are on windows this might look like `D:\\host\\path\\where\\to\\output\\singularity\\image`.\n -`ubuntu:14.04`: the docker image name you wish to convert (it will be pulled from Docker Hub if it does not exist on your host system).\n\n`docker2singularity` uses the Docker daemon located on the host system. It will access the Docker image cache from the host system avoiding having to redownload images that are already present locally.\n\n\nIf you ever need to make changes, you can easily export the squashfs image into either a sandbox folder or ext3 (legacy) image, both of which have writable.\n\n```\nsudo singularity build --sandbox sandbox/ production.simg\nsudo singularity build --writable ext3.img production.simg\n```\n\n### Custom Naming\n\nAdded for version 2.5.1, you can specify the name of your container with the `-n/--name` argument, as follows:\n\n```bash\ndocker run -v /var/run/docker.sock:/var/run/docker.sock \\\n-v /tmp/test:/output \\\n--privileged -t --rm \\\nquay.io/singularity/docker2singularity \\\n--name meatballs ubuntu:14.04\n\n...\n\n$ ls /tmp/test/\nmeatballs.simg\n```\n\n### Inspect Your Image\nNew with `docker2singularity` 2.4, the labels for the container are available with `inspect`:\n\n```bash\n singularity inspect ubuntu_14.04-2017-09-13-3e51deeadc7b.simg \n{\n    \"org.label-schema.singularity.build\": \"squashfs\",\n    \"org.label-schema.docker.version\": \"17.06.2-ce\",\n    \"org.label-schema.schema-version\": \"1.0\",\n    \"org.label-schema.singularity.build-type\": \"docker2singularity\",\n    \"org.label-schema.docker.id\": \"sha256:dea1945146b96542e6e20642830c78df702d524a113605a906397db1db022703\",\n    \"org.label-schema.build-date\": \"2017-10-28-17:19:18\",\n    \"org.label-schema.singularity.version\": \"2.4-dist\",\n    \"org.label-schema.docker.created\": \"2017-09-13\"\n}\n```\n\nas is the runscript and environment\n\n```bash\nsingularity inspect --json -e -r ubuntu_14.04-2017-09-13-3e51deeadc7b.simg \n{\n    \"data\": {\n        \"attributes\": {\n            \"environment\": \"# Custom environment shell code should follow\\n\\n\",\n            \"runscript\": \"#!/bin/sh\\n/bin/bash $@\\n\"\n        },\n        \"type\": \"container\"\n    }\n}\n\n```\n\n### Build a Sandbox Image\nA sandbox image is a folder that is ideal for development. You can view it on your desktop, cd inside and browse, and it works like a Singularity image. To create a sandbox, specify the `-f` flag:\n\n```bash\ndocker run -v /var/run/docker.sock:/var/run/docker.sock \\\n-v /host/path/change/me:/output \\\n--privileged -t --rm \\\nquay.io/singularity/docker2singularity \\\n-f \\\nubuntu:14.04\n```\nImportantly, you can use `--writable`, and if needed, you can convert a sandbox folder into a production image:\n\n```bash\nsudo singularity build sandbox/ production.simg\n```\n\n### Build a Legacy (ext3) Image\nYou can build a legacy ext3 image (with `--writable`) with the `-w` flag. This is an older image format that is more prone to degradation over time, and (building) may not be supported for future versions of the software.\n\n```bash\ndocker run -v /var/run/docker.sock:/var/run/docker.sock \\\n-v /host/path/change/me:/output \\\n--privileged -t --rm \\\nquay.io/singularity/docker2singularity \\\n-w \\\nubuntu:14.04\n```\nYou can also use `--writable` and convert an ext3 image into a production image:\n\n```bash\nsudo singularity build ext3.img production.simg\n```\n\n### Contributed Examples\n\nThe following are a list of brief examples and tutorials generated by the Singularity community for using **docker2singularity**. If you have an example of your own, please [let us know](https://www.github.com/singularityhub/docker2singularity/issues)!\n\n - [docker2singularity-demo](https://github.com/stevekm/docker2singularity-demo): an example of using docker2singularity on MacOS and using Vagrant to test the output Singularity image, complete with notes and a nice Makefile.\n\n\n### Tips for making Docker images compatible with Singularity\n\n - Define all environmental variables using the `ENV` instruction set. Do not rely on `.bashrc`, `.profile`, etc.\n - Define an `ENTRYPOINT` instruction set pointing to the command line interface to your pipeline\n - Do not define `CMD` - rely only on `ENTRYPOINT`\n - You can interactively test the software inside the container by overriding the `ENTRYPOINT`\n   `docker run -i -t --entrypoint /bin/bash bids/example`\n - Do not rely on being able to write anywhere other than the home folder and `/scratch`. Make sure your container runs with the `--read-only --tmpfs /run --tmpfs /tmp` parameters (this emulates the read-only behavior of Singularity)\n - Don’t rely on having elevated user permissions\n - Don’t use the USER instruction set\n\n## FAQ\nHere are some frequently asked questions if you run into trouble! \n\n### \"client is newer than server\" error\nIf you are getting the following error:\n`docker: Error response from daemon: client is newer than server`\n\nYou need to use the `docker info` command to check your docker version and use it to grab the correct corresponding version of `docker2singularity`. For example:\n\n```bash\n     docker run \\        \n     -v /var/run/docker.sock:/var/run/docker.sock \\\n     -v D:\\host\\path\\where\\to\\output\\singularity\\image:/output \\\n     --privileged -t --rm \\\n     singularityware/docker2singularity:1.11 \\            \n     ubuntu:14.04\n```\n\nCurrently only the 1.10, 1.11, 1.12, and 1.13  versions are supported. If you are using an older version of Docker you will need to upgrade.\n\n\n### My cluster/HPC requires Singularity images to include specific mount points\nIf you are getting `WARNING: Non existant bind point (directory) in container: '/shared_fs'` or a similar error when running your Singularity image that means that your Singularity images require custom mount points. To make the error go away you can specify the mount points required by your system when creating the Singularity image:\n\n```bash\n     docker run \\        \n     -v /var/run/docker.sock:/var/run/docker.sock \\\n     -v D:\\host\\path\\where\\to\\output\\singularity\\image:/output \\\n     --privileged -t --rm \\\n     quay.io/singularity/docker2singularity \\            \n     -m \"/shared_fs /custom_mountpoint2\" \\\n     ubuntu:14.04\n```\n\n## Development\n\n### 1. Build the container\n\nYou can build a development container as follows. First, update the [VERSION](VERSION)\nto be correct.\n\n```bash\nVERSION=$(cat VERSION)\nimage=\"quay.io/singularity/docker2singularity:${VERSION}\"\ndocker build -t ${image} .\n```\n\n### 2. Test the container\n\nWe have a [Circle CI](.circleci/config.yml) builder that tests generation of the final\nimage, and basic running to ensure the entrypoint is functioning. Since we cannot run\nthe priviledged Docker daemon on Circle, a [test.sh](test.sh) script is provided for local testing.\n\n```bash\nchmod u+x\n/bin/bash test.sh\n```\n\nIf there are missing tests or you have added new features, please add the test here!\n\n### 3. Documentation\n\nIf you have added new features, please describe usage in the [README.md](README.md) here.\nDon't forget to read the [CONTRIBUTING.md](.github/CONTRIBUTING.md) along with the\n[code of conduct](.github/CODE_OF_CONDUCT.md) and add yourself to the [authors file](.github/AUTHORS.md).\n\n## Acknowledgements\n\nThis work is heavily based on the `docker2singularity` work done by [vsoch](https://github.com/vsoch) \nand [gmkurtzer](https://github.com/gmkurtzer). The original record of the work can be read about\nin [this commit](https://github.com/singularityhub/docker2singularity/commit/d174cadefd90f77f302f4bef5a8cd089eb2da2e4).\nThank you kindly to all the [contributors](.github/AUTHORS.md), and please open an issue if you need help.\n","funding_links":["https://github.com/sponsors/vsoch"],"categories":["Shell"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsingularityhub%2Fdocker2singularity","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsingularityhub%2Fdocker2singularity","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsingularityhub%2Fdocker2singularity/lists"}