What do the Cypress Docker images cypress/base, cypress/browsers and cypress/included contain?
answer
- Three published images stacked on each other
- One of them ships no browser at all
- The middle one adds Chrome, Firefox, Edge
- The top one pins the runner itself
- A fourth generates custom combinations
basics
~20 scypress/base carries Debian, Node.js and the OS packages Cypress needs, but no browser. cypress/browsers adds Chrome, Firefox and Edge. cypress/included adds a tag-pinned Cypress installed globally. cypress/factory generates a custom image when no published combination fits.
solid answer
~40 sThe official images stack. `cypress/base` is Debian plus the operating-system packages Cypress needs, Node.js, npm and Yarn v1 Classic — but no browser, so its tag only chooses a Node.js version. `cypress/browsers` builds on it and adds Chrome, Firefox and Edge, so its tag fixes the combined Node.js and browser versions. `cypress/included` builds on `cypress/browsers` and adds a fixed Cypress installed globally with npm, so the image tag rather than your dependency file decides the runner version. `cypress/factory` is not a ready-made runner image at all: it takes the base operating system and lets you select each component version to generate your own, for combinations no published tag covers. All are Linux (Debian) based and published for `linux/amd64` and `linux/arm64`.
go deeper
Be ready to name the three stacked images in order and say which one has no browser in it. Knowing that the tag encodes Node.js, browser or Cypress versions is enough at this level.
Explain why the split exists: the npm module and the Cypress binary install separately, and the OS libraries and browsers are a third cost. Say which layer each image removes from your job.
An interviewer expects you to justify a choice for a real pipeline, including the arm64 browser gaps, whether the image or the dependency file owns the runner version, and what a browser-less base costs after Cypress 16 deprecated Electron.
Own the standard across repos: one pinned image family, a documented upgrade cadence for Node.js and browser bumps, and a clear rule about who may build from cypress/factory and who then maintains it.
## Why a prebuilt image exists at all Getting Cypress running on a bare Linux container is a three-part job, and each part costs a pipeline job time on every single run. The `cypress` npm module is small — a CLI, TypeScript types and a launcher — while the **Cypress application itself is a large, platform-specific binary** downloaded separately in a `postinstall` step. Before that binary will start, the operating system needs a set of Debian/Ubuntu libraries. And if you want to test in a real browser rather than a bundled one, a browser has to be installed too. The official Cypress Docker images move that work out of the job and into an image that was built once. They are Linux (Debian) based and published for both `linux/amd64` and `linux/arm64`, and picking one is how you fix the environment your tests run in — it stops a pipeline provider silently bumping Node.js or a browser version underneath you. ## The four variants and what each one adds | Image | What it carries | Who picks the Cypress version | | --- | --- | --- | | `cypress/base` | Debian, the OS packages Cypress needs, Node.js, npm, Yarn v1 Classic — **no browser** | your project | | `cypress/browsers` | everything in `base`, plus **Chrome, Firefox and Edge** | your project | | `cypress/included` | everything in `browsers`, plus a **fixed Cypress installed globally with npm** | the image tag | | `cypress/factory` | the base OS image plus per-component version selection | you, when you build it | They genuinely stack: `cypress/browsers` builds on `cypress/base`, and `cypress/included` builds on `cypress/browsers`. The tag is where the variation lives: - a `cypress/base` tag selects the **Node.js** version; - a `cypress/browsers` tag selects the **combined Node.js and browser** versions; - a short `cypress/included` tag selects the **Cypress** version, and the long form spells out the Node.js and browser versions it was built against. `cypress/factory` is different in kind. It is not a ready-to-run runner image but a way to generate one, choosing each component version yourself. Reach for it only when no published tag offers the Node.js, browser and Cypress combination you need — after that you own rebuilding it whenever any one of those moves. ## Choosing one for a multi-package storefront monorepo 1. **Do the packages disagree about the Cypress version?** In a monorepo where `packages/storefront-web` and `packages/checkout` may upgrade Cypress at different times, `cypress/browsers` is usually the right base: each package's own dependency file stays the source of truth, and the image only supplies Node.js and the browsers. 2. **Do you want one pinned runner for the whole repo, with nothing to install?** Then `cypress/included` is attractive: the Cypress binary is already in the image, so a job can execute specs without a binary download at all. The cost is that upgrading Cypress now means changing the image tag, and that a package pinning a different version in its dependency file will quietly install a second copy anyway. 3. **Does nothing published match?** Only then build from `cypress/factory`. ## What Cypress 16 changed about the browser-less option As of Cypress 16, the **bundled Electron browser is deprecated** as a test browser and will be removed in a future major version. That makes `cypress/base` with nothing else installed a poor default: with no installed browser present, a run falls back to Electron, which now emits a deprecation warning and will eventually fail outright. If you are on `cypress/base` today, either move to `cypress/browsers` or install Chrome, Firefox or Edge into the environment yourself. ## Caveats worth checking before you pin a tag - **The architectures are not identical.** On `linux/arm64`, `cypress/browsers` carries Firefox from version 136 and above and Chrome from version 151 and above, and **Edge is not available at all** — its version segment in an arm64 tag is an empty placeholder kept only for multi-platform tag compatibility. A matrix that assumes Edge everywhere breaks the moment a job lands on an ARM runner. - **`cypress/included` pins the runner, not your project.** The Cypress it carries is installed globally. If a package in the monorepo also lists `cypress` as a dev dependency at a different version, installing that package downloads its own binary and you get two. - **A tag is a contract about Node.js too.** Upgrading the image can move the Node.js version your specs and any `setupNodeEvents` code run under, so treat an image bump as a real change, not housekeeping. - **Pinning is the point.** A floating tag re-introduces exactly the drift the image was chosen to eliminate.
- Which Cypress image would you pick if no published tag has the Node.js and browser combination you need?`cypress/factory`. It provides the base operating system image and lets you select each component version individually to generate a custom image. It is the right answer only after you have checked the published `cypress/browsers` and `cypress/included` tags, because from then on you own rebuilding and republishing that image every time Node.js, a browser or Cypress moves.
- As of Cypress 16, why is cypress/base with no browser installed a poor default?Cypress 16 deprecates the bundled Electron browser as a test browser and will remove it in a future major version. A `cypress/base` container with nothing else installed leaves a run falling back to Electron, which now emits a deprecation warning and will eventually fail. Move to `cypress/browsers`, or install Chrome, Firefox or Edge into the environment yourself.
The three stacked images are the same crate packed to three depths: tools only, tools plus browsers, and tools, browsers and the test runner already inside.
saying these in an interview costs you the question
- Thinks cypress/base already contains Chrome or Firefox
- Believes package.json picks the version in cypress/included
- Assumes the official images are Windows or macOS based
- Cannot say what cypress/browsers adds over cypress/base
- Expects an arm64 image to carry exactly the same browsers