GoogleChrome/lighthouse: automated web page auditing from the CLI and Chrome DevTools

The gap Lighthouse fills: one command that returns a structured page audit

Lighthouse targets a specific and awkward job. You have a URL, and you want to know how it behaves on the dimensions that are easy to regress and hard to eyeball: load performance, accessibility, SEO basics, and general developer best practices. The description in package.json puts it plainly: "Automated auditing, performance metrics, and best practices for the web."

The audience is not only front-end engineers. The project ships three entry points for three different kinds of user. Chrome DevTools has a Lighthouse panel, so a designer or product manager can generate a report without touching a terminal. A Chrome extension covers the same ground for people who live in the browser. The Node CLI is the one the README recommends for anyone who wants "more advanced usage, or want to run Lighthouse in an automated fashion". That third path is the one that matters for CI, and it is the one with the sharpest edges.

What makes it useful is the output shape. A run produces a report in HTML or JSON, and the JSON is the part that integrates with other systems. The HTML is for humans reading a single page's problems; the JSON is for storing, diffing and asserting on. The project also hosts an online viewer at googlechrome.github.io/lighthouse/viewer/ where you can drag a JSON report, and the README notes that shared reports are stashed as a secret Gist under your GitHub account, which is a detail worth reading twice before sharing a report from an internal staging host.

How a Lighthouse run is structured: gather, then audit

The mechanism is a two-phase pipeline, and the CLI exposes the split directly. In gather mode the tool launches a browser, loads the page, and collects artifacts, writing them to disk. In audit mode it skips browser interaction entirely, loads those artifacts, runs the audits against them, and generates the report. The README's lifecycle examples show this with the -G, -A and -GA flags.

That separation is the most interesting design decision in the project. It means the expensive, noisy part (driving a real browser against a real network) happens once, and the cheap, deterministic part (evaluating rules against a trace) can be repeated as many times as you like on the same captured artifacts. If you are iterating on thresholds or on a custom configuration, you can re-audit without re-fetching. The default artifact directory is $PWD/latest-run, and you can point -G, -A or -GA at a custom folder.

Around that core sit the audits themselves, organized into categories, plus configuration that controls what runs. The README points to docs/configuration.md for the full option set, and the CLI help output lists flags for logging, asset saving, and trace categories. The project also documents how to author custom audits, which is the extension point for teams whose quality bar includes rules Lighthouse does not ship.

Installing the Node CLI and running a first audit

The README states that Lighthouse requires Node 22 (LTS) or later, and package.json pins the engine at node >=22.19. Install globally with npm, or with yarn global add lighthouse if you prefer yarn. The README gives both forms.

npm install -g lighthouse
# or use yarn:
# yarn global add lighthouse

The first run of the CLI prompts you once about anonymous runtime exception reporting. The README says opting out does not affect your ability to use Lighthouse in any way, so declining is a supported path.

Running an audit needs nothing more than a URL. The README's own example uses airhorner.com, and by default the report lands as an HTML file named after the host and date.

lighthouse https://airhorner.com/
# saves ./<HOST>_<DATE>.report.html

For anything scriptable you want JSON. Passing --output json sends the JSON report to stdout, which is what you would pipe into a file or another process.

lighthouse --output json
# json output sent to stdout

If you want both formats on disk, the README warns that specifying an output path with multiple formats ignores your specified extension for all of them. A single --output-path of ./myfile.json with both json and html produces ./myfile.report.json and ./myfile.report.html. That naming behaviour is easy to miss and will break a CI script that expects the exact path it passed in.

To split the run, gather first and audit later. The artifacts land in ./latest-run by default.

lighthouse http://example.com -G
# launches browser, collects artifacts, saves them to disk (in ./latest-run/) and quits

lighthouse http://example.com -A
# skips browser interaction, loads artifacts from disk, runs audits, generates report

From the DevTools path there is nothing to install beyond Chrome itself: open DevTools, select the Lighthouse panel, and hit "Generate report". The extension installs from the Chrome Web Store.

Where Lighthouse is the wrong tool: variance and the single-number trap

The project's own documentation includes a page called Dealing with variance, which tells you what the maintainers think about reproducibility. Anyone who has tried to use a Lighthouse score as a hard release gate has met the problem: the same URL, audited twice, does not produce the same numbers. The README's FAQ addresses network throttling directly and offers guidance on how to make it better, which is an admission that the default throttling is a model, not a measurement.

This has a concrete consequence. If you assert on a performance score in CI and fail the build when it drops two points, you will get failures that have nothing to do with the commit. The gather/audit split helps here, because re-auditing identical artifacts removes browser and network noise from the comparison, but it does not remove the noise from the original capture. The honest use of the split is to compare audit logic, not to compare two real-world loads.

The second limitation is scope. Lighthouse audits a page as loaded by a browser under its own conditions. It is not a field-data system. It will not tell you what your actual users on actual devices experienced last week, and the README's FAQ about whether results are sent to a remote server confirms the model is a local run, not a telemetry pipeline. Teams that need real-user distributions are looking at a different class of tool, and Lighthouse will not substitute for it.

Third, the CLI is a Node tool with a hard engine floor. Node 22.19 or later is not negotiable per package.json. On a CI image pinned to an older runtime, the install will not give you a working binary, and that is a migration cost, not a bug.

Alternatives and how their approach differs

The clearest alternative in the same problem space is WebPageTest, which the README lists among the web performance services that integrate Lighthouse. The difference in approach is fundamental. WebPageTest runs your page from real browsers on real hardware in named locations, which means the measurement comes from a machine you did not provision. Lighthouse runs a local Chrome instance under a throttling model the tool defines. If your question is "how does this page behave from Singapore on a mid-tier Android device", WebPageTest's model answers it more directly. If your question is "does this page pass a set of structural checks I can script", Lighthouse is the cheaper and more portable answer.

A second comparison is against the platform-native tooling already in Chrome. The DevTools Performance panel gives you a flame chart and lets you inspect a trace interactively. Lighthouse gives you a score and a list of opportunities. They are not competitors so much as different resolutions: the panel is for diagnosing one slow interaction, Lighthouse is for catching a class of regressions across many pages. Teams often run Lighthouse first to find the page, then the panel to find the cause.

The third path is writing your own audit. The README documents authoring custom audits to extend Lighthouse, and the repository has a plugins section. If your quality bar is idiosyncratic, extending Lighthouse keeps you inside one reporting format rather than maintaining a separate checker. That is a real reason to pick it over a homegrown script, and it is also a commitment to the project's audit API.

Maintenance, licensing and the upgrade surface

The repository is not archived, and the last push was on 2026-07-20, which is when v13.4.1 was released. v13.4.0 landed on 2026-06-09 and v13.3.0 on 2026-05-07, so the release cadence across those three versions is roughly one minor or patch release per month.

Licensing is Apache-2.0, which is a permissive licence with an explicit patent grant. That matters for companies that ship Lighthouse inside a product or a CI image, because Apache-2.0 does not carry the copyleft obligations of a GPL-family licence. It does carry notice and attribution requirements, and the LICENSE file in the repository root is the text that governs. This is a description of the licence, not legal advice; if you are redistributing a modified build, read the LICENSE and your own counsel's guidance rather than this paragraph.

The upgrade cost is concentrated in one place: the Node engine floor. package.json requires node >=22.19, and the README states Node 22 (LTS) or later. Every time you bump Lighthouse, check that your CI runtime still satisfies the engine constraint, because a Node upgrade in your pipeline is a much larger change than a Lighthouse version bump. Beyond that, the CLI flags shown in the README (--output, --output-path, --save-assets, -G, -A, -GA) are the surface most integrations touch, and the JSON report schema is the other. The repository keeps a changelog.md at the root, which is where a breaking report-shape change would be announced.

Editorial conclusion

Adopt Lighthouse if you need a repeatable, scriptable audit of a page's performance, accessibility and SEO signals, and you are willing to manage run variance yourself. Do not adopt it if you need a single authoritative performance number for a release gate, or if you expect the default run to match what a real user on a slow phone experiences. Before wiring it into CI, run the same URL twice with the same flags and compare the JSON, then read docs/variability.md in the repository, which is the project's own account of why those numbers move.

Frequently asked questions

Official sources

1. Official documentation
2. Official README
3. Project repository
4. Release notes