Cypress Docker Images

Cypress Docker images are published to Cypress on Docker Hub.

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. We provide multiple tags for various operating systems and specific browser versions. These allow you to target specific combinations you need.

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

Tag Selection

If no tag is specified, for example cypress/included, then the tag latest is used by default: cypress/included:latest. It is however recommended to use a specific image tag to avoid breaking changes when new images are released, especially when they include new major versions of Node.js or Cypress.

Some examples with specific tags including an explanation of the tag meanings are:

cypress/base:18.16.0 Node.js 18.16.0
cypress/browsers:node-18.16.0-chrome-114.0.5735.133-1-ff-114.0.2-edge-114.0.1823.51-1 Node.js 18.16.0 Chrome 114.0.5735.133-1 Firefox 114.0.2 Edge 114.0.1823.51-1
cypress/included:12.17.1 Cypress 12.17.1

Once an image with a specific version tag (except latest) has been published to Cypress on Docker Hub it is frozen. This prevents accidental changes.

When a new version is published, an image copy with the latest tag is also published. This means that the Docker image selected using the latest tag (or selected by default if no tag is specified) will also change over time. Specify an explicit version, for example cypress/base:18.16.0, to access instead a frozen version.

📍Cypress Docker images are offered as a convenience measure. The goal is to offer Node.js, 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.

Docker Hub

All of the images and tags are published to Cypress on Docker Hub under:

Cypress/Factory

Don't see the exact combination of Cypress, Node.js 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.

Examples

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

examples/included-as-non-root shows how to build a new Docker image on top of cypress/included image and run the tests as non-root user node.
examples/included-as-non-root-alternative shows another approach to allow built-in non-root user node to run tests using cypress/included image.
examples/included-as-non-root-mapped shows how to build a Docker image on top of cypress/included that runs with a non-root user that matches the id of the user on the host machine. This way, the permissions on any files created during the test run match the user's permissions on the host machine.
examples/included-with-plugins shows how to use locally installed Cypress plugins while running cypress/included image.

Common problems

Cannot run post-install hook

Some versions of Node.js 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

Firefox not found

By default, the containers run with the root user. However, Firefox by design cannot run with root user, leading to failures such as:

Browser: firefox was not found on your system or is not supported by Cypress.
Can't run because you've entered an invalid browser name.

To resolve this, the container needs to run with user id 1001.

One example using the cypress-io/github-action

name: E2E in custom container
on: push
jobs:
  cypress-run:
    runs-on: ubuntu-22.04
    container: 
     image: cypress/browsers:node18.12.0-chrome106-ff106
     options: --user 1001  
    steps:
      - uses: actions/checkout@v3
      - uses: cypress-io/github-action@v5
        with:
          browser: firefox

Or within a Dockerfile

# Use Cypress base image
FROM cypress/browsers:node18.12.0-chrome106-ff106

# Change to a non-root user
USER 1001

#rest of your dockerfile here

The GitHub Actions Runner creates the /github/home ($HOME) directory with non-root ownership 1001 (runner). Specifying this same user allows Cypress to detect and run Firefox.

Contributing

See CONTRIBUTING.md

License

See LICENSE

cypress-io / cypress-docker-images