---
title: "Unlighthouse CLI - Site-Wide Lighthouse"
description: "Install and run Unlighthouse CLI to scan your entire website with Lighthouse. npm, pnpm, and yarn installation options."
canonical_url: "https://unlighthouse.dev/guide/getting-started/installation"
last_updated: "2026-08-10T16:38:08.438Z"
---

Stop checking pages one at a time. Run a single command and get Lighthouse scores for your entire site in minutes.

```bash
npx unlighthouse --site example.com
```

> <span>
> 
> !TIP
> 
> </span>
> 
> 
> Generate an Agent Skill for this package using [skilld](https://github.com/harlan-zw/skilld):
> 
> ```bash
> npx skilld add unlighthouse
> ```

That's it. Unlighthouse will crawl your site, find every page, run Lighthouse on each one, and open a dashboard where you can watch results stream in live.

<note>

New to Lighthouse? Check the [Core Web Vitals glossary](/glossary) for what [LCP](/glossary/lcp), [CLS](/glossary/cls), and [INP](/glossary/inp) actually mean.

</note>

## Quick Start

Pick your package manager:

<code-group>

```bash [npm]
npx unlighthouse --site https://mysite.com
```

```bash [pnpm]
pnpm dlx unlighthouse --site https://mysite.com
```

```bash [yarn]
yarn dlx unlighthouse --site https://mysite.com
```

</code-group>

A browser window opens automatically showing your scan progress. Results appear as each page completes—no waiting for the full scan to finish.

### What Happens Behind the Scenes

1. **Discovery** — Unlighthouse reads your sitemap and crawls internal links to find every page
2. **Parallel scanning** — Multiple Chrome instances run Lighthouse audits simultaneously
3. **Live results** — Scores stream to your dashboard as each page completes
4. **Smart sampling** — Similar pages (like blog posts) are sampled to avoid redundant scans

### Requirements

- **Node.js 22.18+**
- **Chrome** — Uses your system Chrome. If missing, downloads Chromium automatically.

### Install Globally (Optional)

If you scan sites frequently:

```bash
npm install -g unlighthouse
unlighthouse --site example.com
```

## Common First Scan Issues

### Nothing happening?

Add `--debug` to see what's going on:

```bash
npx unlighthouse --site example.com --debug
```

### WSL Users

Chrome can be tricky in WSL. If you see connection errors, check the [WSL troubleshooting guide](/guide/guides/common-errors#connect-econnrefused-127001port).

### Slow scans?

Your first scan downloads route data and warms up Chrome. Subsequent scans use caching and are much faster.

## Configure Your Scan

Create `unlighthouse.config.ts` in your project root:

```ts
import { defineUnlighthouseConfig } from 'unlighthouse/config'

export default defineUnlighthouseConfig({
  site: 'https://example.com',
  scanner: {
    samples: 3, // Run each page 3x and average (more accurate)
    throttle: true, // Simulate real network conditions
    exclude: ['/admin/*', '/api/*'], // Skip these paths
  },
})
```

Now just run `unlighthouse` without flags—it reads your config automatically.

See [all configuration options](/guide/guides/config).

## What's Next?

- **CI Integration** — Run scans on every deploy, fail builds on performance regressions
- **Large Sites** — Scanning thousands of pages efficiently
- **Authentication** — Scan pages behind login

## Get Help

- **Discord** — Quick questions and community help
- **GitHub Issues** — Bug reports and feature requests