Lighthouse: what it tests and how to run it

Lighthouse is Google's free audit tool. What it checks, four ways to run it, the settings that change your score, and what a lab test can and cannot tell you.

In this guide

What Lighthouse is
The four categories
Four ways to run it
Settings that change the result
Useful command line options
What a Lighthouse run cannot tell you
A sensible routine
Check your own page
Sources

What Lighthouse is

Lighthouse is an automated tool for improving the quality of web pages. You give it a web address. It loads the page in Chrome, runs a set of audits, and writes a report on how the page did. Each audit has a reference page explaining why it matters and how to fix it. You can run it against any page, public or behind a login.

It runs on the machine where you start it, and its results are not sent to a remote server. The exception is PageSpeed Insights, where Google runs Lighthouse for you on its side.

The current version at the time of writing is 13.5. Reports show the version in their footer.

The four categories

Category	What it checks	How the score is made
Performance	How fast the page loads and becomes usable, with metrics and findings	A weighted average of five metrics. See the performance score
Accessibility	Whether people who use screen readers or the keyboard can use the page	A weighted average of automated checks. Each check is pass or fail, and manual checks are listed but not scored. See the three scores that are not about speed
Best practices	Safety and good practice, such as using HTTPS	A weighted average of pass or fail checks. HTTPS, deprecated APIs and third-party cookies count the most
SEO	Basics that let search engines find and understand the page	A weighted average of pass or fail checks. A page blocked from indexing counts for about 31%, and structured data is not scored

Most of this series is about the performance category. The others are worth running too. The SEO checks, for instance, include whether the page is blocked from indexing and whether it returns a good status code, which are also what decides whether a page can appear in the Chrome UX Report.

Four ways to run it

1. PageSpeed Insights. Open pagespeed.web.dev, enter an address and press Analyze. Nothing to install, and it adds real-visitor data from the Chrome UX Report above the lab result. See PageSpeed Insights explained. It can only test public addresses.

2. Chrome DevTools. Lighthouse has its own panel. Open the page in Chrome, press Ctrl+Shift+J (Cmd+Option+J on a Mac), choose the Lighthouse tab, set the options and press Analyze page load. A run takes 10 to 60 seconds. The panel can test local sites and pages behind a login. The Chrome team says to use the DevTools workflow instead of the separate extension unless you have a specific reason, because the extension cannot do that.

3. The command line. This gives the most control and is the way to automate. It needs Node 22 or later and a copy of Chrome.

npm install -g lighthouse
lighthouse https://example.com --view

4. Your own code. The Node module returns the report as text and the result as an object, so a script or a build step can read the numbers.

import fs from 'fs';
import lighthouse from 'lighthouse';
import * as chromeLauncher from 'chrome-launcher';

const chrome = await chromeLauncher.launch({chromeFlags: ['--headless']});
const options = {output: 'html', onlyCategories: ['performance'], port: chrome.port};
const result = await lighthouse('https://example.com', options);

fs.writeFileSync('report.html', result.report);
console.log('Performance score', result.lhr.categories.performance.score * 100);
chrome.kill();

To run it on every release and catch regressions, Lighthouse CI wraps the same tool. The Lighthouse documentation also shows how to run it several times and keep the median.

Settings that change the result

Each of these can move your score, so write down the ones you used.

Setting	What it does	Default
Device	Mobile sets a mobile user agent and a phone-sized screen. Desktop switches those mobile changes off and judges the page against desktop marks	Mobile
Throttling method	Simulated loads the page once without throttling and then calculates what a slow connection would have produced. DevTools really slows the network and processor, which takes longer. Provided applies none	Simulated
Clear storage	Clears the page's saved data before the run, so it measures a first visit. Turn it off to measure a repeat visit	On
Mode	Navigation analyses one page load. Timespan covers a stretch of time with interactions. Snapshot looks at the page in its current state	Navigation
Categories	Which of the four areas to run. Leaving out the ones you do not need makes the run slightly faster	All

The simulated mobile test uses a screen 412 by 823 pixels, a network with a 150 millisecond round trip and about 1.6 megabits per second of download, and a processor slowed down four times. The simulated desktop test uses a 1350 by 940 pixel screen, a 40 millisecond round trip, about 10 megabits per second, and no processor slowdown. Lighthouse describes the mobile network as sitting between the slowest 25% of 4G connections and the fastest 25% of 3G connections.

The processor slowdown is relative to the machine you run on. Lighthouse measures the machine's speed and prints it as "CPU/Memory Power" at the bottom of the report. On a weak computer the fixed fourfold slowdown makes pages look slower than they are, and on a strong one, faster. The command line can set a different multiplier with --throttling.cpuSlowdownMultiplier. Use the same machine for tests you want to compare.

Useful command line options

# Desktop, performance only, saved as a JSON file
lighthouse https://example.com --preset=desktop --only-categories=performance --output=json --output-path=./report.json

# Quiet, without opening a window, for scripts
lighthouse https://example.com --quiet --chrome-flags="--headless"

# Several pages from a list, one report each (the reports folder must already exist)
lighthouse --url-file=./urls.txt --output-path=./reports

Other options worth knowing:

--output takes html, json or csv, and you can ask for more than one.
--throttling-method takes simulate, devtools or provided.
--extra-headers sends headers such as a cookie, which is one way to test a page behind a login.
--blocked-url-patterns blocks requests to addresses that match. Use it to see how the page behaves without one script.
--disable-storage-reset keeps the saved data, for repeat-visit tests.
--save-assets saves the trace of the page load and the network log to disk.

To test a site you must log in to, the documentation describes starting a Chrome window with a debugging port, signing in by hand and pointing Lighthouse at that window. To test on a real phone, connect it with USB debugging and turn off the emulation so Lighthouse does not slow a phone that is already slow.

What a Lighthouse run cannot tell you

Whether real visitors have a good experience. It is one simulated load. The real-visitor result comes from field data. See lab data and field data and the Chrome UX Report.
How the page responds to taps. A standard load test has no interactions, so Interaction to Next Paint is not part of the score. Timespan mode can record layout shifts and script work during interactions, but it gives no overall performance score.
Anything after the first load. Navigation mode cannot analyse form submissions or page changes inside a single-page app. For a journey with several steps, Lighthouse offers user flows, which combine navigation, timespan and snapshot reports.
A steady number. Scores move between runs. See why scores change.
Whether Google has indexed the page. The SEO category checks basics. The real answer is in Search Console.

A sensible routine

Test the pages that matter, not only the home page.
Run both mobile and desktop.
Run each test several times and use the median. Close other programs and use a private window with no extensions, which the Chrome team lists as the first thing to try when a report shows errors.
Save the report. The JSON file can be compared later.
Work from the findings in the report, for the one metric that is weakest. The PageSpeed Insights guide shows how to read them.
After a change, test again with the same settings.

Check your own page

Run the free audit. It uses Lighthouse through PageSpeed Insights, so you get the same kind of report described here, in plain language and with the next step for each problem. To go further, run Lighthouse yourself in DevTools on pages behind a login or on your staging site.

Sources

Lighthouse README: the ways to run it, the command line options and the FAQ.
Lighthouse overview and Lighthouse in DevTools on Chrome for Developers: the workflows and the panel settings.
Lighthouse network and CPU throttling and user flows in the Lighthouse documentation.
Accessibility scoring on Chrome for Developers.