Save Cypress Screenshots to a Custom Folder

Updated 14 November 2026 · Standard formula, shown below

This guide shows you how to configure Cypress to save screenshots (taken on test failure or manually) into a custom folder instead of the default cypress/screenshots directory. You’ll edit your Cypress configuration file and optionally adjust your test code, then verify the new location works.

What You’ll Need

A Cypress project (version 10 or later is assumed; earlier versions use a slightly different config file name).
Access to your project’s root directory and a text editor.
Basic familiarity with JavaScript/JSON syntax.

Step-by-Step

Locate your Cypress configuration file. In Cypress 10+, this is cypress.config.js (or .ts, .mjs) at your project root. For older versions (before 10), it’s cypress.json.
Open the config file in your editor.

Add or modify the screenshotsFolder property. In cypress.config.js, inside the e2e (or component) object, add:

const { defineConfig } = require('cypress');
module.exports = defineConfig({
  e2e: {
    screenshotsFolder: 'cypress/custom-screenshots',
    // other options...
  },
});

For cypress.json (older versions), add the property at the top level:

{ "screenshotsFolder": "cypress/custom-screenshots" }

Choose a folder path. The path is relative to your project root. Use forward slashes (e.g., test-results/screenshots). The folder does not need to exist; Cypress creates it automatically.
Save the config file.
Restart Cypress. Close any running Cypress process (test runner or CLI) and start it again so the config change takes effect.
Run a test that takes a screenshot. You can use cy.screenshot() in a test, or let a test fail to trigger an automatic screenshot.
Verify the screenshot appears in your custom folder. Check the path you set; you should see the screenshot files there. If you don’t, see Troubleshooting below.

Common Mistakes

Editing the wrong config file. Cypress 10+ uses cypress.config.js; older versions use cypress.json. Editing the wrong one has no effect.
Placing the property in the wrong scope. In cypress.config.js, screenshotsFolder must be inside the e2e or component object, not at the top level of the exported object. In cypress.json, it’s top-level.
Using a relative path with a leading slash. A path like /screenshots refers to your filesystem root, not your project. Use a relative path like cypress/screenshots or test-results/screenshots.
Not restarting Cypress. Changes to the config file are not picked up until you restart the Cypress test runner or CLI.
Forgetting to create the folder. Cypress creates it automatically, but if you manually created an empty folder, ensure it’s not read-only.

Tips

Use a dedicated folder for all test artifacts. For example, set screenshotsFolder: 'test-results/screenshots' and videosFolder: 'test-results/videos' to keep everything together.
Take screenshots manually with cy.screenshot(). You can pass a filename: cy.screenshot('homepage') – it will be saved in your custom folder.
Customize screenshot names. Use cy.screenshot('name', { overwrite: true }) to avoid duplicates.
Use environment variables. If you need different folders per environment, you can set screenshotsFolder dynamically using process.env in your config file.
Clean up old screenshots. Add a script to delete the folder before test runs to avoid clutter.

Troubleshooting

Screenshots still go to the default folder. Check that you edited the correct config file and that the property is in the right scope. Restart Cypress completely (kill all processes). If you’re using Cypress 10+, verify you’re editing cypress.config.js and not a leftover cypress.json.

Error: “Cannot find module ‘cypress’” when running config. This is unrelated to the folder change; it means your project dependencies are not installed. Run npm install or yarn install.

The custom folder is created but empty. Ensure your test actually takes a screenshot (via cy.screenshot() or a failure). Check the test output for errors. Also confirm that Cypress has write permissions to the project directory.

Path with spaces or special characters fails. Use forward slashes and avoid spaces; if you must use spaces, quote the path in your config (e.g., 'test results/screenshots').

Changes not applied when running via CI. Make sure the config file is saved and committed to your repository. In CI, run Cypress with --config screenshotsFolder=... if you need to override.

Frequently Asked Questions

Can I set a different screenshots folder for component tests?

Yes, in cypress.config.js you can set component: { screenshotsFolder: '...' } separately from e2e.

Does the folder need to exist before running Cypress?

No, Cypress creates the folder automatically if it doesn’t exist.

Can I use an absolute path?

Yes, but it’s not recommended because it breaks portability. Use a relative path from your project root.

How do I change the screenshot filename pattern?

You can pass a filename to cy.screenshot('filename'). For automatic failure screenshots, the filename is based on the test title; you can override with screenshotOnRunFailure and a custom function, but that’s advanced.

Will videos also be moved to a custom folder?

No, videos have a separate videosFolder option. Set it similarly to move videos.

Why are my screenshots not being saved at all?

Check that you’re not using screenshotOnRunFailure: false (if you expect failure screenshots) and that your test actually executes a screenshot command. Also verify the folder path is writable.

Method: the standard formula for this calculation, rounded as each result states. See how the calculators work or report an error.