# cypress-docker-images: four base images for running Cypress in a container > The cypress-io/cypress-docker-images repository publishes four layered Docker images that bundle the system dependencies, Node toolchain and browsers that Cypress needs, so a CI job does not have to install a browser on every run. The layers are a template, a bare base, a base with browsers and a base with Cypress itself, and the browser set differs between amd64 and arm64. **cypress-io/cypress-docker-images** — Docker images with Cypress dependencies and browsers - Repository: https://github.com/cypress-io/cypress-docker-images - Website: https://on.cypress.io/continuous-integration - Stars: 1,059 · Forks: 389 - Language: Dockerfile - License: MIT - Published: 2026-10-19 · Updated: 2026-10-19 · Language: en - Canonical page: https://hysenlabs.com/projects/cypress-io-cypress-docker-images ## Four images that stack: factory, base, browsers, included The README describes four images, and the division between them is a hierarchy rather than four unrelated products. cypress/factory is a base image template used with ARGs to create a custom Docker image, so it is the layer you build on. cypress/base has all the operating system dependencies, no Cypress and no browsers. cypress/browsers adds the browsers to that same dependency base. cypress/included is built on top of cypress/browsers and adds Cypress installed globally. The practical value of the split is that you choose how much you take. A team that manages its own browsers through another mechanism can take base and stop there. A team that wants Cypress and the three browsers preinstalled takes included. A team that wants a specific browser set builds from factory. The images are published to the cypress organisation on Docker Hub, and each has its own tag list. ## The base is debian:13-slim, and the platforms are amd64 and arm64 The images are Linux based and use the debian:13-slim Docker image as the default base image. Each of the four is published with multi-platform support for Linux/amd64 and Linux/arm64. That second platform is where the practical details get interesting, because the images are usable on CI systems that support Docker and locally under Docker Desktop on Mac, Linux or Windows. For Windows the README adds a caveat that matters more than it first appears: the documentation and scripts in the repository assume that Docker Desktop for Windows runs in a virtual Linux environment, with pointers to the WSL2 and WSLg documentation. In other words, the Windows path is WSL underneath, not native Windows containers. The arm64 support is what makes the images usable on Apple Silicon runners, and it comes with the browser caveats discussed below. ## What is actually inside: Node.js, npm, corepack and Yarn Classic The component bundle section lists what the base, browsers and included images carry, and the detail that matters is the version tracking. Node.js is included, and images with a latest tag track the Node.js Active LTS release line, with the linked Node.js distribution policy explaining how bundled components are handled. npm comes through Node.js, and the documented way to update it is npm install -g npm@. corepack also comes through Node.js, and is noted as dropped in Node.js 25 and above, with npm install -g corepack@ as the way to install or update it. Yarn v1 Classic is installed globally with npm, and is noted as dropped in Node.js 26 and above. The pattern here is that these images freeze a toolchain at image build time, and the README documents the escape hatch for changing it rather than leaving you to discover it. ## Browser coverage is not the same on arm64 as on amd64 The browser table is the section that decides whether an image fits your setup. Google Chrome and Mozilla Firefox are present on both Linux/amd64 and Linux/arm64. Microsoft Edge is present on amd64, and on arm64 the table points at issue 1189 rather than a plain yes, which is the kind of honest gap that matters when you plan to run an arm64 CI runner. The lowest available browser versions for Linux/arm64 images are Chrome 151 and Firefox 136. The cypress/included images are built on top of cypress/browsers and therefore contain the same browser set, and the Tags section for both images shows which versions of the browsers are loaded into each tag. The README also notes that Cypress officially supports the latest three major versions of Chrome, Firefox and Edge, and recommends using up to date images for supportability, which links the image cadence to the browser support window. ## Chrome for Testing is deliberately not in the images Chrome for Testing is a separate story, and the README is explicit that it is not included in the cypress/browsers or cypress/included images. Support for it starts at Cypress 13.17.0 and above. There are two documented routes to add it. The first is the factory image, which provides the CHROME_FOR_TESTING_VERSION parameter to add Chrome for Testing optionally to a custom image. The second is the examples/chrome-for-testing/ directory, which describes an alternate way to install it using the @puppeteer/browsers command-line utility. The platform availability is narrow and worth checking before you plan around it: Chrome for Testing is available for linux/amd64 since 113.0.5672.0, and for linux/arm64 since 153.0.8001.0. The version floor on arm64 is much higher, so a pipeline that needs an older Chrome for Testing on an Apple Silicon runner will not find it in the image. ## geckodriver ships with Firefox 139.0.1 and above The cypress/browsers and cypress/included images with Firefox 139.0.1 and above are built with the Mozilla geckodriver included. The stated reason is that this driver is needed to test when using Firefox with Cypress versions 13.15.1 and above. In other words, the driver is not a convenience, it is a requirement for a particular combination of browser and Cypress version, and the images that predate Firefox 139.0.1 do not have it. The README then introduces an environment variable beginning with GECKODRIVER to configure the driver. The rule of thumb that follows from the rest of it is simple enough: use an image tag new enough to carry the driver, and confirm the environment variable before you rely on it. ## The repository is a set of Dockerfiles with a small JavaScript toolchain around it The primary language of this repository is Dockerfile, and the top level layout reflects that. There is a base/ directory, a base-internal/ directory, a browsers/ directory with a browsers-internal/ counterpart, an included/ directory and a factory/ directory, and the README links directly into those directories for the details of each. Alongside them sit examples/, including basic-mini/, basic/, chrome-for-testing/, chromium/, firefox-esr/, included-as-non-root/ and test-all-examples.sh, so the examples are executable references rather than documentation snippets. The JavaScript around the Dockerfiles is small. The package.json holds four scripts, a markdown link check with markdown-link-check and a configuration file, prettier for formatting with a format and format:check pair, and eslint for linting. The devDependencies pin eslint 10 with the Cypress eslint plugin, and the repository also carries renovate.json for dependency updates, a.node-version and.nvmrc for the Node version, and a.prettierrc and.prettierignore. ## Licence, maintenance and how to consume the images The package manifest states the MIT licence and the project is marked private, which is normal for a repository that publishes artefacts rather than a package, and the LICENSE file is at the top level. The last push to the repository was on 2026-10-16 and there are no GitHub releases, since the deliverable is a set of tagged Docker images on Docker Hub rather than a versioned tarball. Consuming them is a pull rather than an install, so a CI job declares the image as its build environment and the tag pins the browser and toolchain versions. The one decision to make carefully is which of the four to use, because the wrong choice means either shipping a browser you did not want or building the image yourself on every run. The examples/test-all-examples.sh script and the per-directory READMEs referenced from the main table are the places to look when you want to copy a known good pattern rather than write one. ## Conclusion cypress-docker-images suits a team whose CI runs Cypress in containers and wants the browser and system dependencies pinned and reproducible instead of installed at every job start, and who needs arm64 runners as well as amd64 ones. It is the wrong tool if you run Cypress on a developer machine without Docker, since these images add nothing there, and a poor fit for a project that needs a browser version or a system package that the published tags do not carry, because the fix then means building your own image from cypress/factory. Before adopting it, check the Tags section for the browser versions actually present in the tag you plan to pin, note that Edge is not present on Linux/arm64 per the tracked issue, and remember that Chrome for Testing is not included in the browsers or included images and has to be added through the factory image or the examples directory. ## FAQ ### What is the difference between the cypress Docker images? cypress/factory is a base template used with ARGs to build a custom image. cypress/base has the operating system dependencies but no Cypress and no browsers, cypress/browsers adds the browsers to that base, and cypress/included is built on browsers and adds Cypress installed globally. ### Which platforms do the cypress Docker images support? They are Linux based, using debian:13-slim as the default base image, and each is published with multi-platform support for Linux/amd64 and Linux/arm64. On Windows, the documentation and scripts assume Docker Desktop runs in a virtual Linux environment using WSL2 and WSLg. ### Which browsers are available on Linux/arm64 in the cypress images? Google Chrome and Mozilla Firefox are available on both Linux/amd64 and Linux/arm64, while Microsoft Edge on arm64 points at issue 1189. The lowest available versions for arm64 images are Chrome 151 and Firefox 136, and Cypress officially supports the latest three major versions of Chrome, Firefox and Edge. ### Is Chrome for Testing included in the cypress Docker images? No, it is not included in the cypress/browsers or cypress/included images. It is supported by Cypress 13.17.0 and above, and you add it through the CHROME_FOR_TESTING_VERSION parameter of the factory image or through the examples/chrome-for-testing/ directory using the @puppeteer/browsers utility. ### What Node.js tooling do the cypress Docker images bundle? They include Node.js, where latest tags track the Node.js Active LTS release line, plus npm and corepack through Node.js and Yarn v1 Classic installed globally with npm. corepack is dropped in Node.js 25 and above, and Yarn v1 Classic in Node.js 26 and above, and each can be updated with an npm install -g command. ## Sources - [cypress-io/cypress-docker-images on GitHub](https://github.com/cypress-io/cypress-docker-images) - [Issues](https://github.com/cypress-io/cypress-docker-images/issues) - [License: MIT](https://github.com/cypress-io/cypress-docker-images/blob/master/LICENSE) - [Project website](https://on.cypress.io/continuous-integration) - [README](https://github.com/cypress-io/cypress-docker-images/blob/master/README.md) --- Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/cypress-io-cypress-docker-images