---
title: "Lighthouse CI (LHCI): Complete Guide to @lhci/cli in 2026"
description: "Complete guide to Lighthouse CI (@lhci/cli) from Google. Automate Lighthouse audits in CI/CD, enforce performance budgets, prevent regressions. Install, configure, GitHub Actions."
canonical_url: "https://unlighthouse.dev/learn-lighthouse/lighthouse-ci"
last_updated: "2026-04-13"
---

Lighthouse CI (LHCI) is Google's official tool for running Lighthouse audits in continuous integration pipelines. It catches performance regressions before they reach production.

<note>

**Current Version**: LHCI 0.15.x uses Lighthouse 12.6.1. The PWA category was [removed in Lighthouse 12](https://developers.google.com/speed/docs/insights/release_notes) (May 2024). Lighthouse 13 is not yet supported as it requires Node 22.19+.

</note>

## What is Lighthouse CI?

Lighthouse CI is a suite of tools that integrate Lighthouse into your CI/CD workflow:

- **@lhci/cli**: Command-line tool for running audits (~2M monthly [npm](https://npmjs.com) downloads)
- **@lhci/server**: Optional server for storing historical data
- **GitHub App**: Status checks on pull requests

## Why Use Lighthouse CI?

[Elite performers are 2.6x more likely](https://dora.dev/publications/2023-dora-report/) to have integrated automated performance testing into their CI/CD pipelines. Without it, regressions slip through:

1. Developer fixes performance issues
2. PR gets merged
3. Next week, someone adds a 500KB image
4. Performance tanks, nobody notices until users complain

LHCI solves this by running Lighthouse on every commit and failing builds that don't meet your standards.

## Key Features

- **Regression prevention**: Fail builds when [Core Web Vitals](/learn-lighthouse/core-web-vitals) like [LCP](/learn-lighthouse/lcp), [CLS](/learn-lighthouse/cls), and [TBT](/glossary/tbt) (proxy for [INP](/learn-lighthouse/inp)) drop
- **Performance budgets**: Set thresholds for scores and resource sizes
- **Historical tracking**: Compare builds over time
- **Variance reduction**: Run multiple times, use median results
- **GitHub integration**: Status checks and PR comments

## Quick Start

Install and run:

```bash
npm install -g @lhci/cli
lhci autorun --collect.url=https://example.com --upload.target=temporary-public-storage
```

Or with a config file (`lighthouserc.js`):

```js
export default {
  ci: {
    collect: {
      url: ['https://example.com/'],
    },
    upload: {
      target: 'temporary-public-storage',
    },
  },
}
```

Then run:

```bash
lhci autorun
```

## Setting Up Lighthouse Continuous Integration

Getting Lighthouse into your CI pipeline takes four steps: install `@lhci/cli`, add a config file with your URLs and budgets, wire it into your CI workflow (GitHub Actions, GitLab CI, etc.), and optionally connect the LHCI server for historical tracking. The tutorials below walk through each platform in detail.

## How It Works

The `lhci autorun` command executes three steps:

1. **collect**: Runs Lighthouse N times per URL
2. **assert**: Checks results against budgets/assertions
3. **upload**: Stores results (temporary storage, filesystem, or LHCI server)

Run `lhci healthcheck --fatal` separately to verify Chrome and config before autorun.

Results are saved to `.lighthouseci/` locally.

## What LHCI Measures

Lighthouse CI audits four categories on every run:

- **Performance**: [Core Web Vitals](/learn-lighthouse/core-web-vitals) ([LCP](/learn-lighthouse/lcp), [CLS](/learn-lighthouse/cls), [TBT](/glossary/tbt) as proxy for [INP](/learn-lighthouse/inp)) and other speed metrics
- **Accessibility**: [Screen reader support, color contrast, ARIA](/learn-lighthouse/accessibility)
- **SEO**: [Meta tags, structured data, mobile-friendliness](/learn-lighthouse/seo)
- **Best Practices**: [HTTPS, console errors, deprecated APIs](/learn-lighthouse/best-practices)

Each category gets a 0-100 score. Set thresholds in your config to block merges when scores drop.

<note type="info">

**How scores map to percentiles**: A score of 50 means you're faster than 75% of sites. A score of 90 puts you in the [top 8% of all websites](https://developer.chrome.com/docs/lighthouse/performance/performance-scoring). Currently, only [53% of origins pass all Core Web Vitals](https://almanac.httparchive.org/en/2025/performance).

</note>

## Prerequisites

- [Node.js](https://nodejs.org/en) 18+
- Chrome/Chromium installed
- A URL to test (can be localhost with `startServerCommand`)

## Tutorials

<card-group>
<card icon="i-simple-icons-githubactions" title="GitHub Actions" to="/learn-lighthouse/lighthouse-ci/github-actions">

Set up LHCI with GitHub Actions and status checks.

</card>

<card icon="i-simple-icons-gitlab" title="GitLab CI" to="/learn-lighthouse/lighthouse-ci/gitlab-ci">

Configure LHCI for GitLab CI/CD pipelines.

</card>

<card icon="i-heroicons-cog-6-tooth" title="Configuration" to="/learn-lighthouse/lighthouse-ci/configuration">

All lighthouserc.js options explained.

</card>

<card icon="i-heroicons-chart-bar" title="Performance Budgets" to="/learn-lighthouse/lighthouse-ci/budgets">

Set and enforce performance thresholds.

</card>

<card icon="i-heroicons-server" title="LHCI Server" to="/learn-lighthouse/lighthouse-ci/server">

Self-host a dashboard for historical tracking.

</card>

<card icon="i-heroicons-wrench-screwdriver" title="Troubleshooting" to="/learn-lighthouse/lighthouse-ci/troubleshooting">

Fix common LHCI issues.

</card>
</card-group>

## Performance Impact

Why invest in performance testing? Research shows direct business impact:

- [BBC loses 10% of users](https://www.creativebloq.com/features/how-the-bbc-builds-websites-that-scale) for every additional second of load time
- [Amazon estimates](https://www.cloudflare.com/learning/performance/more/website-performance-conversion-rates/) every 100ms of latency costs 1% in sales
- [Google research](https://web.dev/articles/why-speed-matters) shows bounce probability increases 90% as load time goes from 1s to 5s

## Resources

- [GitHub Repository](https://github.com/GoogleChrome/lighthouse-ci)
- [Official Documentation](https://googlechrome.github.io/lighthouse-ci/)
- [npm Package](https://www.npmjs.com/package/@lhci/cli)
i)