# Configuration

```mdx-code-block
import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';
```

All defaults in Puppeteer can be customized in two ways:

1. [Configuration files](#configuration-files) (**recommended**)
2. [Environment variables](#environment-variables)

:::caution

Note that some options are only customizable through environment variables (such
as `HTTPS_PROXY`).

:::

:::caution

Puppeteer's configuration files and environment variables are ignored by `puppeteer-core`.

:::

## Configuration files

Configuration files are the **recommended** choice for configuring Puppeteer.
Puppeteer will look up the file tree for any of the following formats:

- `.puppeteerrc.cjs`,
- `.puppeteerrc.js`,
- `.puppeteerrc` (YAML/JSON),
- `.puppeteerrc.json`,
- `.puppeteerrc.yaml`,
- `puppeteer.config.js`, and
- `puppeteer.config.cjs`

Puppeteer will also read a `puppeteer` key from your application's
`package.json`.

See the [`Configuration`](../api/puppeteer.configuration) interface for possible
options.

:::caution

After adding a configuration file, you may need to remove and reinstall
`puppeteer` for it to take effect if the changes affect installation.

:::

### Examples

#### Changing the default cache directory

Starting in v19.0.0, Puppeteer stores browsers in `~/.cache/puppeteer` to
globally cache browsers between installation. This can cause problems if
`puppeteer` is packed during some build step and moved to a fresh location. The
following configuration can solve this issue (reinstall `puppeteer` to take
effect):

```js title="project-directory/.puppeteerrc.cjs"
const {join} = require('path');

/**
 * @type {import("puppeteer").Configuration}
 */
module.exports = {
  // Changes the cache location for Puppeteer.
  cacheDirectory: join(__dirname, '.cache', 'puppeteer'),
};
```

:::note

Notice this is only possible with CommonJS configuration files as information
about the ambient environment is needed (in this case, `__dirname`).

:::

#### Enabling experiments

By default, experiments are turned off, but they can be individually turned on
using the [`experiments`](../api/puppeteer.configuration) key.

For example, if you want to enable ARM-native macOS chromium, you can use

<Tabs>
<TabItem value="CommonJS">

```js title=".puppeteerrc.cjs"
/**
 * @type {import("puppeteer").Configuration}
 */
module.exports = {
  experiments: {
    macArmChromiumEnabled: true,
  },
};
```

</TabItem>
<TabItem value="JSON">

```json title=".puppeteerrc.json"
{
  "experiments": {
    "macArmChromiumEnabled": true
  }
}
```

</TabItem>
<TabItem value="YAML">

```yaml title=".puppeteerrc.yaml"
experiments:
  macArmChromiumEnabled: true
```

</TabItem>
</Tabs>

## Environment variables

Along with configuration files, Puppeteer looks for certain
[environment variables](https://en.wikipedia.org/wiki/Environment_variable) for
customizing behavior. Environment variables will always override configuration
file options when applicable.

The following options are _environment-only_ options

- `HTTP_PROXY`, `HTTPS_PROXY`, `NO_PROXY` - defines HTTP proxy settings that are
  used to download and run the browser.

All other options can be found in the documentation for the
[`Configuration`](../api/puppeteer.configuration) interface.