---
id: app/references/advanced-installation
title: 'Advanced installation in Cypress: custom binary, cache & proxy'
description: >-
  Configure advanced Cypress installation: install a custom binary or version,
  change the cache folder, install behind a proxy, mirror, or custom CA, and
  skip the binary download.
section: app
source_path: docs/app/references/advanced-installation.mdx
version: e6c8d867c21227247f14714fb5690c7c018983c5
updated_at: '2026-08-08T12:39:37.868Z'
---
# Advanced Installation

Most people install Cypress with a single `npm install cypress --save-dev` and never need anything on this page. The defaults are designed to "just work": Cypress downloads the right binary for your operating system, caches it so it can be reused across projects, and launches it when you run a test.

This guide is for the situations where those defaults don't fit. It exists because real-world environments are messy: corporate proxies, air-gapped CI, locked-down certificate stores, disk-constrained build agents, and containerized editors all change how (and whether) Cypress can reach the internet and where it can write files. Each setting below is an escape hatch for one of those constraints.

What you'll learn

*   How Cypress installs the npm module and the binary, and why that split matters
*   How to install a custom version, URL, or local file, or skip the binary entirely
*   How to install behind a proxy, download mirror, custom URL template, or custom certificate authority
*   How to relocate, inspect, and prune the binary cache
*   How to opt out of crash reports and commercial messaging
*   How to set up Cypress in WSL, Dev Containers, and GitHub Codespaces

## How Cypress installs

Understanding the install model makes almost every setting on this page self-explanatory. Installing Cypress happens in two distinct steps:

1.  **The npm module** (`cypress`) is added to your project like any other dependency. This package is small: it's the CLI, TypeScript types, and the `cypress` binary launcher. It is _not_ the Cypress application itself.
2.  **The binary** (the actual Cypress application, including the bundled browsers' automation layer) is downloaded in a [`postinstall`](https://docs.npmjs.com/cli/using-npm/scripts) step. Because the binary is large and platform-specific, it is stored in a **global cache** outside `node_modules` so a single download can be shared by every project on the machine.

When you later run `cypress open` or `cypress run`, the npm module locates the matching binary in the cache and launches it.

This two-step model is the "why" behind most of the variables below:

*   Because the binary is downloaded separately, you can point that download at a different version, URL, or local file. See [Install binary](#Install-binary).
*   Because it comes over the network, restricted environments need a way to route through a [proxy](#Proxy-configuration), a [mirror](#Mirroring), or a [custom CA](#Using-a-custom-certificate-authority-CA).
*   Because it lives in a shared cache, you can relocate, inspect, and prune that cache. See [Binary cache](#Binary-cache).

## Environment variables

Almost every behavior on this page is driven by a system-level (OS) environment variable. These are set in your shell, CI configuration, or `.npmrc`.

| Name | Description |
| --- | --- |
| `CYPRESS_INSTALL_BINARY` | [Sets which Cypress binary to install: a version, URL, or local file](#Install-binary) |
| `CYPRESS_DOWNLOAD_MIRROR` | [Downloads the Cypress binary from a mirror server](#Mirroring) |
| `CYPRESS_DOWNLOAD_PATH_TEMPLATE` | [Builds a custom URL to download the Cypress binary from](#Download-path-template) |
| `CYPRESS_CACHE_FOLDER` | [Changes the location of the Cypress binary cache](#Binary-cache) |
| `CYPRESS_RUN_BINARY` | [Sets the path to the Cypress binary to launch at run time](#Run-binary) |
| `CYPRESS_VERIFY_TIMEOUT` | Overrides the timeout duration for the `verify` command. The default value is 30000. |
| `CYPRESS_SKIP_VERIFY` | Skips the [`verify` command](/llm/markdown/app/references/command-line.md#cypress-verify) when set to `true` |

### When you'd reach for each

The descriptions above say what each variable does. Here is the problem each one typically solves, so you can find the right tool for your situation:

*   **`CYPRESS_INSTALL_BINARY`**: Use this when the binary npm would install isn't the one you want. Common goals: pin a binary version that differs from the npm package, install from an internal URL when `download.cypress.io` is blocked, or install from a local `.zip` on an offline machine. Setting it to `0` skips the binary download entirely, which is handy for building base Docker images or splitting install and download into separate, debuggable steps.
*   **`CYPRESS_DOWNLOAD_MIRROR`**: Use this when your network blocks the public download server but you host an internal copy of it. It swaps the download host for your mirror while keeping the same URL layout, so many machines can install without each pinning a one-off URL.
*   **`CYPRESS_DOWNLOAD_PATH_TEMPLATE`**: Use this when your internal artifact store doesn't match the `download.cypress.io` URL layout. It lets you describe exactly how your server lays out files so Cypress can build the correct URL per platform and version.
*   **`CYPRESS_CACHE_FOLDER`**: Use this to control where the downloaded binary is stored. The most common goal is faster CI: point it at a directory your CI provider caches between runs so the download becomes a cache hit. It's also useful on locked-down machines where the default cache location isn't writable.
*   **`CYPRESS_RUN_BINARY`**: Use this when you want to launch a specific binary already on disk instead of the one resolved from the cache, for example a binary you unzipped to a known location.
*   **`CYPRESS_VERIFY_TIMEOUT`**: Use this to adjust how long Cypress waits for the one-time binary verification step before timing out. The default is 30 seconds (`30000` ms); raise it on slow or heavily loaded machines where verification needs more time.
*   **`CYPRESS_SKIP_VERIFY`**: Use this to skip binary verification, for example when the binary lives in a read-only location and verification can't write its results.

### Setting variables via npm config or package.json

You don't have to export a shell variable to configure these options. This is valuable because shell exports don't persist across machines or CI agents, whereas committing the setting to your repo does, so the whole team and your CI get the same behavior automatically.

Every `CYPRESS_*` variable above can be set as a real environment variable, or through your npm configuration. Cypress resolves each variable in the following order, using the first value it finds:

1.  The actual environment variable (e.g. `CYPRESS_INSTALL_BINARY`)
2.  `npm_config_<name>` (set via `.npmrc` or `npm config`)
3.  The lowercase `npm_config_<name>`
4.  `npm_package_config_<name>` (set via a `config` block in `package.json`)

This means options like `CYPRESS_INSTALL_BINARY`, `CYPRESS_CACHE_FOLDER`, and `CYPRESS_DOWNLOAD_MIRROR` can all be configured in `.npmrc`:

.npmrc

```
cypress_install_binary=https://company.domain.com/cypress.zipcypress_cache_folder=/path/to/cypress/cachecypress_download_mirror=https://company.domain.com
```

or in a `config` block of your `package.json`:

package.json

```
{  "config": {    "cypress_install_binary": "https://company.domain.com/cypress.zip",    "cypress_cache_folder": "/path/to/cypress/cache",    "cypress_download_mirror": "https://company.domain.com"  }}
```

## Proxy configuration

Corporate networks frequently force outbound traffic through a proxy. Because the binary download happens outside your application code (in npm's `postinstall`), Cypress reads the proxy settings npm and the OS already use, so you usually don't have to configure anything Cypress-specific.

System [proxy properties](/llm/markdown/app/references/proxy-configuration.md) `http_proxy`, `https_proxy` and `no_proxy` are respected for the download of the Cypress binary. You can also use the npm properties `npm_config_proxy` and `npm_config_https_proxy`. Those have lower priority, so they will only be used if the system properties are being resolved to not use a proxy.

## Install binary

`CYPRESS_INSTALL_BINARY` controls **which** binary the `postinstall` step fetches. People most often need this when the version published to npm isn't the one they want, or when the public download server isn't reachable from where they're installing.

To override what is installed, you set `CYPRESS_INSTALL_BINARY` alongside the `npm install` command.

**This is helpful if you want to:**

*   Override the installed binary version for a single install, without editing the `cypress` version committed in your `package.json`. This is useful for quickly testing a different version locally or in CI without changing committed files.
    
    ```
    CYPRESS_INSTALL_BINARY=15.16.0 npm install
    ```
    
*   Specify an external URL (to bypass a corporate firewall).
    
    ```
    CYPRESS_INSTALL_BINARY=https://company.domain.com/cypress.zip npm install cypress
    ```
    
*   Specify a file to install locally instead of using the internet.
    
    ```
    CYPRESS_INSTALL_BINARY=/local/path/to/cypress.zip npm install cypress
    ```
    

In all cases, the fact that the binary was installed from a custom location _is not saved in your `package.json` file_. Every repeated installation needs to use the same environment variable to install the same binary. If you'd rather not repeat the variable each time, set it in [npm config or `package.json`](#Setting-variables-via-npm-config-or-packagejson) so it's applied automatically on every install.

### Skipping installation

Sometimes you want the npm module without the binary download, for example, to build a base Docker image and add the binary in a later layer, or to install the binary yourself with debug output. Setting `CYPRESS_INSTALL_BINARY=0` skips the download entirely.

```
CYPRESS_INSTALL_BINARY=0 npm install
```

Now Cypress will skip its install phase once the npm module is installed.

### Troubleshoot installation

When an install fails, the useful output is usually hidden: package managers run `postinstall` in the background by default. The fix is to run `cypress install` on its own with [debug logging](/llm/markdown/app/references/troubleshooting.md#Log-sources) enabled so you can see exactly where the download or unzip step breaks.

*   npm
*   Yarn
*   pnpm
*   Bun

```
CYPRESS_INSTALL_BINARY=0 npm install cypress --save-devDEBUG=cypress:cli* npx cypress install
```

```
CYPRESS_INSTALL_BINARY=0 yarn add cypress --devDEBUG=cypress:cli* yarn cypress install
```

```
CYPRESS_INSTALL_BINARY=0 pnpm add --save-dev cypressDEBUG=cypress:cli* pnpm cypress install
```

```
CYPRESS_INSTALL_BINARY=0 bun add --dev cypressDEBUG=cypress:cli* bunx cypress install
```

To set environment variables `CYPRESS_INSTALL_BINARY` and `DEBUG` in Windows CMD or PowerShell terminals, refer to examples in [Print DEBUG Logs](/llm/markdown/app/references/troubleshooting.md#Print-DEBUG-logs).

In Continuous Integration (CI) use the following commands to display debug logs from the Cypress binary installation:

*   npm
*   Yarn
*   pnpm
*   Bun

```
DEBUG=cypress:cli* npm ci --foreground-scripts
```

```
yarn install --frozen-lockfile --ignore-scripts # Yarn v1 Classic onlyDEBUG=cypress:cli* yarn cypress install
```

```
pnpm install --frozen-lockfile --ignore-scriptsDEBUG=cypress:cli* pnpm cypress install
```

```
bun install --frozen-lockfile --ignore-scriptsDEBUG=cypress:cli* bunx cypress install
```

### Install pre-release version

Occasionally you'll want to verify a fix or try a feature before it ships in an official release. The Cypress team may also ask you to install a pre-release to confirm that an issue you reported is resolved before it's released. Cypress publishes a pre-release binary for individual commits on `develop`, which you can install the same way as any custom binary.

1.  Open up the list of commits to `develop` on the Cypress repo: [https://github.com/cypress-io/cypress/commits/develop](https://github.com/cypress-io/cypress/commits/develop)
2.  Find the commit that you would like to install the pre-release version of. Click the comment icon (highlighted in red below):
    
3.  You should see several comments from the `cypress-bot` user with instructions for installing Cypress pre-releases. Pick the one that corresponds to your operating system and CPU architecture, and follow the instructions there to install the pre-release.

The `cypress-bot` comments point at pre-release binaries hosted on the Cypress CDN. If you are scripting pre-release installs, the URLs follow this pattern:

```
https://cdn.cypress.io/beta/binary/<version>/<platform>-<arch>/<branch>-<sha>/cypress.zip
```

*   `<version>`: the Cypress version being built (e.g. `15.16.0`)
*   `<platform>-<arch>`: one of the supported [platform/architecture combinations](#Mirroring) (e.g. `darwin-arm64`, `linux-x64`)
*   `<branch>`: the branch the binary was built from (e.g. `develop`)
*   `<sha>`: the full commit SHA

You can install a pre-release binary directly by pointing [`CYPRESS_INSTALL_BINARY`](#Install-binary) at one of these URLs:

```
CYPRESS_INSTALL_BINARY=https://cdn.cypress.io/beta/binary/15.16.0/darwin-arm64/develop-abcdef1234567890/cypress.zip npm install cypress
```

Cypress pre-releases are only available for 60 days after they are built. Do not rely on these being available past 60 days.

## Installing behind a firewall or mirror

These sections all address the same root problem: the machine running `npm install` can't download from `https://download.cypress.io` directly. The simplest fix is to allowlist the URLs Cypress needs. If that isn't possible, host the binary yourself and point Cypress at it with a known download URL, a full mirror, a custom URL layout, or a private certificate authority.

### Allowlist URLs for installation

If your VPN, firewall, or proxy only permits traffic to approved hosts, add the following to your allowlist so the binary can be downloaded during `npm install`:

| URL | Purpose |
| --- | --- |
| `https://download.cypress.io` | Resolves the correct binary for your version and platform |
| `https://cdn.cypress.io` | Serves the actual binary `.zip` (download requests redirect here, and pre-release binaries are hosted here) |
| `https://registry.npmjs.org` | Installs the `cypress` npm package (or your configured npm registry) |

If you also run tests against Cypress Cloud, you'll need to allow additional URLs. See the full list of [subdomains to allow on a restrictive VPN](/llm/markdown/cloud/faq.md#Im-working-with-a-restrictive-VPN-Which-subdomains-do-I-have-to-allow-on-my-VPN-for-Cypress-Cloud-to-work-properly).

### Download URLs

If you want to download a specific Cypress version for a given platform (Operating System), you can get it from our CDN. This is the building block for air-gapped installs: download the `.zip` once, host it internally, and point `CYPRESS_INSTALL_BINARY` at it.

**The download server URL is `https://download.cypress.io`.**

We currently have the following downloads available:

*   Windows 64-bit (`?platform=win32&arch=x64`)
*   Linux 64-bit (`?platform=linux`)
*   macOS 64-bit (`?platform=darwin`)

Here are the available download URLs:

See [https://download.cypress.io/desktop.json](https://download.cypress.io/desktop.json) for all available platforms.

| Method | URL | Description |
| --- | --- | --- |
| `GET` | `/desktop` | Download Cypress at latest version (platform auto-detected) |
| `GET` | `/desktop.json` | Returns JSON containing latest available CDN destinations |
| `GET` | `/desktop?platform=p&arch=a` | Download Cypress for a specific platform and/or architecture |
| `GET` | `/desktop/:version` | Download Cypress with a specified version |
| `GET` | `/desktop/:version?platform=p&arch=a` | Download Cypress with a specified version and platform and/or architecture |

**Example of downloading Cypress `15.16.0` for Windows 64-bit:**

```
https://download.cypress.io/desktop/15.16.0?platform=win32&arch=x64
```

### Mirroring

When many machines install Cypress from inside a restricted network, hosting a mirror is more maintainable than pinning every project to a one-off URL. Set `CYPRESS_DOWNLOAD_MIRROR` to replace the download server URL `https://download.cypress.io` with your own mirror.

For example:

```
CYPRESS_DOWNLOAD_MIRROR="https://www.example.com" cypress install
```

Cypress will then attempt to download a binary with this format: `https://www.example.com/desktop/:version?platform=p&arch=a`

Your mirror server must handle requests to `/desktop/:version` with `platform` and `arch` query parameters, and serve the appropriate Cypress binary as a `.zip` file.

**Supported platform and architecture combinations:**

| `platform` | `arch` | Notes |
| --- | --- | --- |
| `linux` | `x64` | Linux Intel/AMD 64-bit |
| `linux` | `arm64` | Linux ARM64 (e.g. AWS Graviton, Apple Silicon containers) |
| `darwin` | `x64` | macOS Intel |
| `darwin` | `arm64` | macOS Apple Silicon |
| `win32` | `x64` | Windows; also used for ARM64 Windows (no native ARM64 binary) |

On Windows ARM64 machines, Cypress automatically substitutes `arm64` with `x64` when building the download URL, so your mirror will only ever receive `win32` requests with `arch=x64`.

On macOS, Cypress detects the machine's real architecture rather than relying on `process.arch`. If an x64 build of Node is running under Rosetta on Apple Silicon, Cypress still requests the native `darwin-arm64` binary. This is why the downloaded architecture can differ from `process.arch` (which would report `x64`), and your mirror may receive `arch=arm64` requests from an x64 Node process.

If your mirror uses a different URL structure than `download.cypress.io`, use `CYPRESS_DOWNLOAD_PATH_TEMPLATE` together with `CYPRESS_DOWNLOAD_MIRROR`. See [Download path template](#Download-path-template) for examples.

### Download path template

A plain mirror assumes your server mimics the `download.cypress.io` layout. `CYPRESS_DOWNLOAD_PATH_TEMPLATE` removes that assumption: it lets you describe exactly how your artifact store lays out files, so Cypress can build the right URL for the platform and version being installed.

**The following replacements are supported:**

| Placeholder | Replaced with | Example |
| --- | --- | --- |
| `${endpoint}` | The full base URL, including the version path | `https://download.cypress.io/desktop/15.16.0` |
| `${platform}` | The platform being installed on | `win32`, `linux`, `darwin` |
| `${arch}` | The architecture being installed on | `x64`, `arm64` (always `x64` on Windows ARM64) |
| `${version}` | The version number being installed | `15.16.0` |

`${endpoint}` expands to `<base>/desktop/<version>`. If `CYPRESS_DOWNLOAD_MIRROR` is set, its value is used as `<base>` instead of `https://download.cypress.io`, but `/desktop/<version>` is still appended.

#### Examples:

To install the binary from a download mirror that matches the exact file structure of `https://cdn.cypress.io`:

*   macOS
*   Linux
*   Windows

```
export CYPRESS_DOWNLOAD_MIRROR=https://cypress-download.localexport CYPRESS_DOWNLOAD_PATH_TEMPLATE='${endpoint}/${platform}-${arch}/cypress.zip'
```

```
export CYPRESS_DOWNLOAD_MIRROR=https://cypress-download.localexport CYPRESS_DOWNLOAD_PATH_TEMPLATE='${endpoint}/${platform}-${arch}/cypress.zip'
```

Command Prompt

```
set CYPRESS_DOWNLOAD_MIRROR=https://cypress-download.localset CYPRESS_DOWNLOAD_PATH_TEMPLATE='${endpoint}/${platform}-${arch}/cypress.zip'
```

PowerShell

```
$env:CYPRESS_DOWNLOAD_MIRROR = "https://cypress-download.local"$env:CYPRESS_DOWNLOAD_PATH_TEMPLATE = '${endpoint}/${platform}-${arch}/cypress.zip'
```

**Example of a resulting URL:** `https://cypress-download.local/desktop/15.16.0/linux-x64/cypress.zip`

To install the binary from a download server with a custom file structure:

*   macOS
*   Linux
*   Windows

```
export CYPRESS_DOWNLOAD_PATH_TEMPLATE='${endpoint}/${platform}-${arch}/cypress.zip'
```

```
export CYPRESS_DOWNLOAD_PATH_TEMPLATE='${endpoint}/${platform}-${arch}/cypress.zip'
```

Command Prompt

```
set CYPRESS_DOWNLOAD_PATH_TEMPLATE='${endpoint}/${platform}-${arch}/cypress.zip'
```

PowerShell

```
$env:CYPRESS_DOWNLOAD_PATH_TEMPLATE = '${endpoint}/${platform}-${arch}/cypress.zip'
```

**Example of a resulting URL:** `https://software.local/cypress/linux/x64/15.16.0/cypress.zip`

To define `CYPRESS_DOWNLOAD_PATH_TEMPLATE` in `.npmrc`, put a backslash before every `$`:

.npmrc

```
CYPRESS_DOWNLOAD_PATH_TEMPLATE=\${endpoint}/\${platform}-\${arch}/cypress.zip
```

### Using a custom certificate authority (CA)

Networks that intercept TLS (or serve downloads from an internal host with a private certificate) will cause the download to fail certificate validation. Pointing Cypress at your organization's CA lets the download succeed without disabling TLS verification.

Cypress can be configured to use the `ca` and `cafile` options from your npm config file to download the Cypress binary.

For example, to use the CA at `/home/person/certs/ca.crt` when downloading Cypress, add the following to your `.npmrc`:

.npmrc

```
cafile=/home/person/certs/ca.crt
```

Alternatively, you can supply the certificate inline with the `ca` option instead of pointing to a file. This is equivalent to setting the `npm_config_ca` environment variable. Newlines in the PEM certificate are represented with `\n`:

.npmrc

```
ca="-----BEGIN CERTIFICATE-----\nMIID...\n-----END CERTIFICATE-----"
```

To supply more than one certificate, set `ca` to an array of strings. The same value can also be provided through the environment:

*   macOS
*   Linux
*   Windows

```
export npm_config_ca="-----BEGIN CERTIFICATE-----\nMIID...\n-----END CERTIFICATE-----"
```

```
export npm_config_ca="-----BEGIN CERTIFICATE-----\nMIID...\n-----END CERTIFICATE-----"
```

Command Prompt

```
set npm_config_ca="-----BEGIN CERTIFICATE-----\nMIID...\n-----END CERTIFICATE-----"
```

PowerShell

```
$env:npm_config_ca = "-----BEGIN CERTIFICATE-----\nMIID...\n-----END CERTIFICATE-----"
```

If neither `cafile` nor `ca` are set, Cypress looks at the system environment variable `NODE_EXTRA_CA_CERTS` and uses the corresponding certificate(s) as an extension for the trusted certificate authority when downloading the Cypress binary.

Note that the npm config is used as a replacement, and the node environment variable is used as an extension.

## Binary cache

Once downloaded, the binary lives in a global cache so it can be reused across projects and CI runs instead of being re-downloaded every time. Knowing where that cache is (and being able to move it) is what makes Cypress fast in CI and predictable on shared machines.

By default, global cache folders are:

*   **MacOS**: `~/Library/Caches/Cypress`
*   **Linux**: `~/.cache/Cypress`
*   **Windows**: `/AppData/Local/Cypress/Cache`

The most common reason to relocate the cache is CI caching: pointing `CYPRESS_CACHE_FOLDER` at a directory your CI provider persists between runs turns a multi-minute download into a cache hit. Set the environment variable to override the default:

*   macOS
*   Linux
*   Windows

```
export CYPRESS_CACHE_FOLDER=~/Desktop/cypress_cache
```

```
export CYPRESS_CACHE_FOLDER=~/.cache/Cypress
```

Command Prompt

```
set CYPRESS_CACHE_FOLDER=~/.cache/Cypress
```

PowerShell

```
$env:CYPRESS_CACHE_FOLDER = "~/.cache/Cypress"
```

Cypress will automatically replace the `~` with the user's home directory. So you can pass `CYPRESS_CACHE_FOLDER` as a string from CI configuration files, for example:

```
environment:  CYPRESS_CACHE_FOLDER: '~/.cache/Cypress'
```

If you use Bun, [`BUN_INSTALL_CACHE_DIR`](https://bun.sh/docs/install/cache) controls Bun's package cache and is independent of `CYPRESS_CACHE_FOLDER`, which stores the Cypress binary.

See also [Continuous Integration - Caching](/llm/markdown/app/continuous-integration/overview.md#Caching) section in the documentation.

`CYPRESS_CACHE_FOLDER` will need to exist every time cypress is launched. To ensure this, consider exporting this environment variable. For example, in a `.bash_profile` (MacOS, Linux), or using `RegEdit` (Windows).

### Managing the binary cache

Over time the cache accumulates a binary per Cypress version you've used, which can quietly consume disk space on CI agents and developer machines. The [`cypress cache`](/llm/markdown/app/references/command-line.md#cypress-cache-command) command lets you inspect and prune it. Run these with the appropriate package manager prefix described in [How to run commands](/llm/markdown/app/references/command-line.md#How-to-run-commands).

| Command | Description |
| --- | --- |
| [`cypress cache list`](/llm/markdown/app/references/command-line.md#cypress-cache-list) | Lists the cached Cypress versions. Add `--size` to also report each version's size. |
| [`cypress cache path`](/llm/markdown/app/references/command-line.md#cypress-cache-path) | Prints the path to the Cypress binary cache. |
| [`cypress cache prune`](/llm/markdown/app/references/command-line.md#cypress-cache-prune) | Deletes every cached binary except the version currently in use. |
| [`cypress cache clear`](/llm/markdown/app/references/command-line.md#cypress-cache-clear) | Deletes all cached Cypress binaries. |

### Run binary

`CYPRESS_RUN_BINARY` is the run-time counterpart to the install-time settings above: it tells the npm module to launch a specific binary on disk instead of the one it would normally resolve from the cache. This is useful when you've unzipped a binary to a known location and want to run it directly.

`CYPRESS_RUN_BINARY` should be a path to an already unzipped Cypress binary executable. The Cypress commands [open](/llm/markdown/app/references/command-line.md#cypress-open), [run](/llm/markdown/app/references/command-line.md#cypress-run) and [verify](/llm/markdown/app/references/command-line.md#cypress-verify) will then launch the provided binary.

The following example [cypress run](/llm/markdown/app/references/command-line.md#cypress-run) commands assume that you have first downloaded the Cypress binary to the default `Downloads` directory of your operating system.

Depending on how you then unzip the downloaded Cypress binary `cypress.zip` file, using a CLI command or alternatively a GUI interface, the directory structure may include one additional top-level directory named `cypress`, which you may need to add to the path defined by `CYPRESS_RUN_BINARY`.

If available, use the following to avoid the additional top-level directory level:

```
unzip -q cypress
```

The examples below are for npm. If you are using Yarn or pnpm as package manager, replace `npx` with `yarn` or `pnpm` as appropriate. See [How to run commands](/llm/markdown/app/references/command-line.md#How-to-run-commands).

*   macOS
*   Linux
*   Windows

```
CYPRESS_RUN_BINARY=~/Downloads/Cypress.app/Contents/MacOS/Cypress npx cypress run
```

```
CYPRESS_RUN_BINARY=~/Downloads/Cypress/Cypress npx cypress run
```

```
CYPRESS_RUN_BINARY=C:\Users\YourUsername\Downloads\Cypress\Cypress.exe npx cypress run
```

Cypress assumes that `CYPRESS_RUN_BINARY` points to a writeable directory structure so that it can save and re-use the results of verifying the Cypress binary. If you encounter a `permission denied` failure message from [cypress verify](/llm/markdown/app/references/command-line.md#cypress-verify), you may be able to work around the failure by setting the environment variable `CYPRESS_SKIP_VERIFY` to `true`.

*   macOS
*   Linux
*   Windows

```
export CYPRESS_SKIP_VERIFY=true
```

```
export CYPRESS_SKIP_VERIFY=true
```

Command Prompt

```
set CYPRESS_SKIP_VERIFY=true
```

PowerShell

```
$env:CYPRESS_SKIP_VERIFY = "true"
```

## Privacy and messaging

Cypress sends a small amount of data outbound and occasionally surfaces commercial messages. Both are off-switches you may want in privacy-sensitive or noise-sensitive environments.

### Opt out of sending exception data to Cypress

When an exception is thrown regarding Cypress, we send along the exception data to `https://api.cypress.io`. We solely use this information to help develop a better product.

If you would like to opt out of sending any exception data to Cypress, you can do so by setting `CYPRESS_CRASH_REPORTS=0` in your system environment variables. Set the variable before installing Cypress, using the approach for your operating system. To make this permanent, add the command to your shell's `~/.profile` (for example, `~/.zshprofile` or `~/.bash_profile`) so it runs on every login.

*   macOS
*   Linux
*   Windows

```
export CYPRESS_CRASH_REPORTS=0
```

```
export CYPRESS_CRASH_REPORTS=0
```

Command Prompt

```
set CYPRESS_CRASH_REPORTS=0
```

PowerShell

```
$env:CYPRESS_CRASH_REPORTS = "0"
```

### Opt out of Cypress commercial messaging

Cypress may occasionally display messages in your CI logs related to our commercial offerings and how they could benefit you during your workflows.

If you would like to opt out of all commercial messaging, you can do so by setting `CYPRESS_COMMERCIAL_RECOMMENDATIONS=0` in your system environment variables.

*   macOS
*   Linux
*   Windows

```
export CYPRESS_COMMERCIAL_RECOMMENDATIONS=0
```

```
export CYPRESS_COMMERCIAL_RECOMMENDATIONS=0
```

Command Prompt

```
set CYPRESS_COMMERCIAL_RECOMMENDATIONS=0
```

PowerShell

```
$env:CYPRESS_COMMERCIAL_RECOMMENDATIONS = "0"
```

## Environment-specific setup

These environments need extra setup because they don't provide a graphical display the way a normal desktop OS does, which is what the interactive Test Runner needs.

### Windows Subsystem for Linux

Cypress requires an [X-server](https://en.wikipedia.org/wiki/X.Org_Server) (X11) to display the Cypress UI from a Windows Subsystem for Linux installation. This requirement is met by current versions of Windows Subsystem for Linux (WSL2) with X11 support being included through Windows Subsystem for Linux GUI (WSLg).

Refer to [GitHub: Windows Subsystem for Linux GUI (WSLg)](https://github.com/microsoft/wslg) for installation instructions on Ubuntu and install the [prerequisite Linux packages](/llm/markdown/app/get-started/install-cypress.md#Linux-Prerequisites) before running Cypress.

Refer to Microsoft Learn [Windows Subsystem for Linux Documentation](https://learn.microsoft.com/en-us/windows/wsl/) for additional information.

Cypress.io does not specifically support the use of Cypress under Windows Subsystem for Linux (WSL). If you want to report an issue, please ensure that you can reproduce it without using WSL on one of the Cypress [supported operating systems](/llm/markdown/app/get-started/install-cypress.md#Operating-System).

### Dev Containers and GitHub Codespaces

[Dev Containers](https://containers.dev/) (VS Code Dev Containers) and [GitHub Codespaces](https://github.com/features/codespaces) provide containerized Linux development environments.

**Running tests headlessly** with `cypress run` works without any extra display configuration when the container image includes the required [Linux prerequisites](/llm/markdown/app/get-started/install-cypress.md#Linux-Prerequisites). The official [Cypress Docker images](/llm/markdown/app/continuous-integration/overview.md#Cypress-Docker-Images) already include all prerequisites.

**Running the interactive Test Runner** with `cypress open` requires a graphical display, which containers do not provide by default. The simplest solution is the [`desktop-lite` Dev Container feature](https://github.com/devcontainers/features/tree/main/src/desktop-lite), which installs a lightweight browser-accessible desktop inside the container.

Add the feature to your `devcontainer.json` and forward the necessary ports:

devcontainer.json

```
{  "image": "cypress/included",  "forwardPorts": [6080, 5901],  "features": {    "ghcr.io/devcontainers/features/desktop-lite:1": {}  },  "portsAttributes": {    "6080": {      "label": "desktop"    }  },  "postCreateCommand": "npm install && cypress install"}
```

After rebuilding the container, open `http://localhost:6080` in your browser and log in with the default password `vscode`. Running `cypress open` in the terminal will display the Cypress UI in that browser-based desktop.

Replace `cypress/included` with the specific [Cypress Docker image tag](https://github.com/cypress-io/cypress-docker-images) that matches your required Cypress and Node.js versions (for example, `cypress/included:14.0.0`).

Cypress.io does not specifically support the use of Cypress in Dev Containers or GitHub Codespaces. If you want to report an issue, please ensure that you can reproduce it without a containerized environment on one of the Cypress [supported operating systems](/llm/markdown/app/get-started/install-cypress.md#Operating-System).

## Uninstall Cypress

Removing Cypress is two-sided because of the install model: uninstalling the npm module removes it from your project, but the cached binaries and app data persist on disk until you remove them too.

To uninstall Cypress from a project, use the same package manager you used to [install Cypress](/llm/markdown/app/get-started/install-cypress.md):

*   npm
*   Yarn
*   pnpm
*   Bun

```
npm uninstall cypress
```

```
yarn remove cypress
```

```
pnpm remove cypress
```

```
bun remove cypress
```

To uninstall all cached Cypress binary versions, use the [cypress cache clear](/llm/markdown/app/references/command-line.md#cypress-cache-clear) command with the appropriate package manager prefix described in [How to run commands](/llm/markdown/app/references/command-line.md#How-to-run-commands). To remove only the older cached versions while keeping the one currently in use, use [cypress cache prune](/llm/markdown/app/references/command-line.md#cypress-cache-prune) instead. Alternatively, delete the [Cypress binary cache](#Binary-cache) (see above) manually. See [Managing the binary cache](#Managing-the-binary-cache) for the full set of cache commands.

**To delete cached [Cypress App Data](/llm/markdown/app/references/troubleshooting.md#Clear-App-Data), manually delete the following directories / folders:**

*   macOS: `~/Library/Application Support/Cypress`
*   Linux: `~/.config/Cypress`
*   Windows: `$APPDATA/Cypress` (POSIX-syntax) or `%APPDATA%\Cypress` (Windows-syntax)

Refer to your package manager documentation for details of package manager `cache clean` commands to remove other packages cached by npm, Yarn, pnpm or Bun.

## See also

*   [Install Cypress](/llm/markdown/app/get-started/install-cypress.md)
*   [Command Line](/llm/markdown/app/references/command-line.md) - `cypress cache`, `cypress verify`, and `cypress install`
*   [Troubleshooting](/llm/markdown/app/references/troubleshooting.md)
*   [Continuous Integration Overview](/llm/markdown/app/continuous-integration/overview.md) - caching the binary and Cypress Docker images