Skip to content


Switch branches/tags

Name already in use

A tag already exists with the provided branch name. Many Git commands accept both tag and branch names, so creating this branch may cause unexpected behavior. Are you sure you want to create this branch?


Failed to load latest commit information.
Latest commit message
Commit time
August 5, 2019 12:55

Cypress Docker Images CircleCI

These images provide all of the required dependencies for running Cypress in Docker.

We build four images, click on the image name to see the available tags and versions.

Image Default Description Monthly pulls
cypress/factory cypress/factory:1.0.0 A base image template which can be used with ARGs to create a custom docker image. Docker Pulls
cypress/base cypress/base:16.13.0 All operating system dependencies, no Cypress, and no browsers. Docker Pulls
cypress/browsers cypress/browsers:chrome69 All operating system dependencies, no Cypress, and some browsers. Docker Pulls
cypress/included cypress/included:9.4.1 All operating system dependencies, Cypress, and some browsers installed globally. Docker Pulls

Of these images, we provide multiple tags for various operating systems and specific browser versions. These allow you to target specific combinations you need.

Best practice

It is recommended to use a specific image tag, and not rely on the default tag. For example, it is better to use cypress/base:12 than cypress/base. Even better it is to use full version of the image, like cypress/base:12.18.0 - we will never overwrite the existing Docker images to prevent accidental changes.

📍Cypress Docker images are offered as a convenience measure. The goal is to offer Node, Browser and Cypress versions to streamline running tests in CI or other non-public, sandboxed environments.

Some preparations and optimizations are not included. For example, given the near infinite permutations, images are not monitored for security vulnerabilities. Additionally, once images are published they are considered immutable and cannot be patched. That means (hypothetically) older images could become more vulnerable over time.

This means they should not be used for production deployment and security scans should be performed as-needed by users of these images.


All of the images and tags are published to DockerHub under


Don't see the exact combination of cypress, node and browser versions you need for your test environment? Checkout our cypress/factory. You can use it to generate a custom image to fit your needs.


These images have all dependencies necessary to install and run Cypress. Just install your NPM dependencies (including Cypress) and run the tests. We utilize many of these docker images in our own projects, with different CI providers.

Check out our docs for examples.

If you want to use the cypress/included image, read Run Cypress with a single Docker command

Common problems

Cannot run post-install hook

Some versions of Node restrict running the postinstall hook with the following error message:

lifecycle realworld@1.0.0~postinstall: cannot run in wd realworld@1.0.0

In that case run install with npm install --unsafe-perm flag, or set an environment variable in the container

npm_config_unsafe_perm: true

Blank screen in Chrome

When running headed tests with X11 forwarding in Cypress v4 you might see a blank Chrome screen. Try disabling memory sharing by setting the following environment variables:

export QT_X11_NO_MITSHM=1
export _X11_NO_MITSHM=1
export _MITSHM=0

See issue #270