---
title: "Puppeteer Launch Options for Lighthouse Audits · Unlighthouse"
meta:
  "og:description": "Configure Puppeteer launch options for headless Chrome: --no-sandbox, Docker args, viewport, executable path, and navigation hooks. Copy-paste configs for CI and Docker."
  "og:title": "Puppeteer Launch Options for Lighthouse Audits · Unlighthouse"
  description: "Configure Puppeteer launch options for headless Chrome: --no-sandbox, Docker args, viewport, executable path, and navigation hooks. Copy-paste configs for CI and Docker."
---

**Guides**

# **Puppeteer Launch Options for Lighthouse Audits**

[Copy for LLMs](https://unlighthouse.dev/guide/guides/puppeteer.md)

Unlighthouse uses [**Puppeteer**](https://pptr.dev/) to control Chrome for Lighthouse audits. Configure browser behavior, navigation hooks, and Chrome flags via `puppeteerOptions`.

## [All Available Options](#all-available-options)

```
export default defineUnlighthouseConfig({
  puppeteerOptions: {
    // See: https://pptr.dev/api/puppeteer.launchoptions
  },
})
```

Full reference: [**Puppeteer LaunchOptions API**](https://pptr.dev/api/puppeteer.launchoptions)

## [Common Configurations](#common-configurations)

### [Headless Mode](#headless-mode)

```
// Run with visible browser (debugging)
export default defineUnlighthouseConfig({
  puppeteerOptions: {
    headless: false,
  },
})
```

### [Custom Chrome Executable](#custom-chrome-executable)

```
export default defineUnlighthouseConfig({
  puppeteerOptions: {
    executablePath: '/usr/bin/google-chrome',
  },
})
```

### [Chrome Arguments](#chrome-arguments)

Common args for CI/Docker environments:

```
export default defineUnlighthouseConfig({
  puppeteerOptions: {
    args: [
      '--no-sandbox',
      '--disable-setuid-sandbox',
      '--disable-dev-shm-usage',
      '--disable-gpu',
    ],
  },
})
```

### [Viewport Settings](#viewport-settings)

```
export default defineUnlighthouseConfig({
  puppeteerOptions: {
    defaultViewport: {
      width: 1920,
      height: 1080,
    },
  },
})
```

### [Timeout Configuration](#timeout-configuration)

```
export default defineUnlighthouseConfig({
  puppeteerOptions: {
    timeout: 60000, // 60 seconds
  },
})
```

### [User Data Directory](#user-data-directory)

Persist browser data between runs:

```
export default defineUnlighthouseConfig({
  puppeteerOptions: {
    userDataDir: './.puppeteer-data',
  },
})
```

## [Navigation Hooks](#navigation-hooks)

Hook into Puppeteer's page navigation for custom logic.

### [Before Page Load](#before-page-load)

```
export default defineUnlighthouseConfig({
  hooks: {
    'puppeteer:before-goto': async (page) => {
      // Set localStorage before navigation
      await page.evaluateOnNewDocument((token) => {
        localStorage.setItem('auth', token)
      }, process.env.AUTH_TOKEN)
    },
  },
})
```

### [Modify Page Content](#modify-page-content)

```
export default defineUnlighthouseConfig({
  hooks: {
    'puppeteer:before-goto': async (page) => {
      page.waitForNavigation().then(async () => {
        // Remove elements that cause CLS
        await page.evaluate(() => {
          document.querySelector('.cookie-banner')?.remove()
        })
      })
    },
  },
})
```

## [Troubleshooting](#troubleshooting)

### [Chrome not found](#chrome-not-found)

See [**Chrome Dependency Guide**](https://unlighthouse.dev/guide/guides/chrome-dependency).

### [Connection refused in Docker](#connection-refused-in-docker)

Add `--no-sandbox` and `--disable-dev-shm-usage` args.

### [Memory issues](#memory-issues)

Reduce concurrent workers or add `--disable-dev-shm-usage`.

[Edit this page](https://github.com/harlan-zw/unlighthouse/edit/main/docs/1.guide/guides/puppeteer.md)

[Markdown For LLMs](https://unlighthouse.dev/guide/guides/puppeteer.md)

**Did this page help you? **

Anything that could be done better? :)

Help us improve this page. You can [edit this page](https://github.com/harlan-zw/unlighthouse/edit/main/docs/1.guide/guides/puppeteer.md) on GitHub or provide anonymous feedback below.

[**Lighthouse Config** Customize Lighthouse audit categories, throttling, and desktop/mobile presets in Unlighthouse. Pass any lighthouseOptions directly.](https://unlighthouse.dev/guide/guides/lighthouse) [**Route Definitions** Configure route discovery and custom sampling patterns for better page organization and intelligent scanning.](https://unlighthouse.dev/guide/guides/route-definitions)

**On this page **

- [All Available Options](#all-available-options)
- [Common Configurations](#common-configurations)
- [Navigation Hooks](#navigation-hooks)
- [Troubleshooting](#troubleshooting)