Lighthouse: Web Performance and Accessibility Auditing
What Lighthouse is
Lighthouse is Google Chrome's open-source auditing tool for web pages. The README describes it in one line: "Lighthouse analyzes web apps and web pages, collecting modern performance metrics and insights on developer best practices." It loads a page in Chrome, records a performance trace and a log of DevTools Protocol events, runs a set of audits over that data and produces a scored report in HTML, JSON or CSV. The same engine sits behind the "Lighthouse" panel in Chrome DevTools, a Chrome extension, the lighthouse Node CLI and a programmatic Node module, and each release note in changelog.md says when that version is expected to reach DevTools and PageSpeed Insights.
The README is clear about privacy: "Lighthouse runs locally, auditing a page using a local version of the Chrome browser installed on the machine. Report results are never processed or beaconed to a remote server."
The repository is GoogleChrome/lighthouse, written in JavaScript, created on 8 March 2016 and licensed under Apache-2.0. The npm package is lighthouse; version 13.6.0 declares "engines": {"node": ">=22.19"}, while the README phrases the requirement as "Node 22 (LTS) or later". The package is ESM ("type": "module") and installs three binaries: lighthouse, chrome-debug and smokehouse.
How it works: gatherers, audits and Lantern
The architecture doc, which calls itself "some incomplete notes", splits a run into a few stages:
- Driver. Talks to Chrome through Puppeteer and the Chrome DevTools Protocol.
- Gatherers. Collect raw data from the page with little post-processing. Running with
--gather-modesaves the three main outputs:artifacts.json,trace.json(which "you can view in the DevTools Performance panel") anddevtoolslog.json. - Audits. Each audit takes artifacts as input and resolves to a score between 0 and 1, plus optional details.
- Report. The HTML report is rendered client-side from the Lighthouse Result object (LHR), the same JSON the CLI prints with
--output=json.
Because gathering and auditing are separate, -G collects artifacts and quits, and -A re-runs audits over artifacts already on disk.
Throttling is where most newcomers get confused. By default Lighthouse uses simulated throttling, implemented by a component called Lantern: it loads the page without throttling, then models how the same load would play out on a slow network and CPU. The throttling guide calls it "both very fast and deterministic" but admits "inherent inaccuracy". The Lantern doc quantifies it from a study of 300 URLs: Lantern is "~6-13% more inaccurate than DevTools throttling", with rank correlations "within ~.04-.07". Two other methods are available: devtools (request-level throttling applied in the browser) and provided (no throttling from Lighthouse; use whatever the environment already imposes).
The default mobile profile is spelled out in the throttling doc: 150 ms latency, 1.6 Mbps down and 750 Kbps up, which "represent roughly the bottom 25% of 4G connections and top 25% of 3G connections", plus a constant 4x CPU slowdown. The README's FAQ translates that into "a typical mobile user on a 4G connection and a mid-tier ~$200 phone".
Categories, scoring and what changed in Lighthouse 13
A default run produces category scores for Performance, Accessibility, Best Practices and SEO. Per the scoring doc, Best Practices and SEO audits are equally weighted, and Accessibility is a weighted average of pass/fail audits, so "if half your buttons have screenreader friendly names, and half do not ... you get a 0". Performance scoring is documented on developer.chrome.com rather than in the repository.
The 13.x line has changed the report noticeably:
- Insights replace older audits. 13.0.0 (10 October 2025) removed audits "replaced by performance insights", along with
offscreen-images,uses-rel-preload,third-party-facades,font-sizeand others. Audits now have ids such asimage-delivery-insight,render-blocking-insightandlcp-discovery-insight. 13.0.0 also made an unknown category inonlyCategoriesan error. - A fifth category. 13.3.0 (7 May 2026) added an "Agentic Browsing" category to the default config. In the 13.6.0 report its description says the checks target "browsable websites for AI agents" and WebMCP integrations, and adds "This category is still under development and subject to change." Its audits include an accessibility-tree check, WebMCP checks,
llms-txtand an ARD (Agentic Resource Discovery) manifest audit. - Bulk URLs from the CLI. 13.6.0 (27 October 2026) accepts several URLs or a
--url-file, and default filenames now include the URL path.
Key features
- Three run modes. Navigation (a cold page load), timespan (an arbitrary period with interactions) and snapshot (the page in its current state), combinable into multi-step user flows through the Node API.
- Configurable runs.
--only-categories,--only-audits,--skip-audits, presets (perf,experimental,desktop) and config files that extendlighthouse:default. - Throttling control. Simulated, DevTools or provided throttling, with per-value flags such as
--throttling.cpuSlowdownMultiplierand abenchmarkIndexin every report for calibrating CPU slowdown. - Machine-readable output. The LHR JSON carries each audit's
score,numericValueanddetails, plusruntimeErrorfor detecting bad runs. - Extensibility. Plugins (npm modules named
lighthouse-plugin-*) add audits and a category through a "semver-stable API"; custom configs can additionally gather new artifacts and modify core categories. - Authenticated pages. Options range from scripting the login with Puppeteer to
--extra-headersand thechrome-debugbinary.
Getting started
The README's CLI install is a global npm package:
npm install -g lighthouse
Then point it at a URL; by default the report is written to an HTML file in the working directory:
lighthouse https://airhorner.com/
On a server or in a container, the headless guide gives this form, which also works around the small default /dev/shm in Docker:
lighthouse --chrome-flags="--headless --no-sandbox --disable-dev-shm-usage" https://github.com
Restricting categories and auditing a list of URLs:
lighthouse <url> --only-categories=performance,seo
lighthouse --url-file=./urls.txt --output-path=./reports
Programmatic use, from docs/readme.md; the Node module does not launch Chrome itself:
import fs from 'fs';
import lighthouse from 'lighthouse';
import * as chromeLauncher from 'chrome-launcher';
const chrome = await chromeLauncher.launch({chromeFlags: ['--headless']});
const options = {logLevel: 'info', output: 'html', onlyCategories: ['performance'], port: chrome.port};
const runnerResult = await lighthouse('https://example.com', options);
User flows need a Puppeteer page. The skeleton from docs/user-flows.md:
import puppeteer from 'puppeteer';
import {startFlow} from 'lighthouse';
const browser = await puppeteer.launch();
const page = await browser.newPage();
const flow = await startFlow(page);
await flow.startTimespan();
await flow.endTimespan();
await flow.snapshot();
writeFileSync('report.html', await flow.generateReport());
Hands-on: Lighthouse 13.6.0 on a flawed page and its fix
To see what the tool reports and how stable its numbers are, Lighthouse was installed and run on 18 November 2026 in a Linux cloud VM: Ubuntu 24.04.5, 2 vCPUs, about 8 GB RAM, no display, running as root, with Node.js 22.23.5 and npm 10.9.9. The browser was the Chrome for Testing 153.0.8010.12 build that ships with Playwright, selected with the CHROME_PATH environment variable, as the CLI help describes. Two pages were served from localhost by a small node:http server:
- Flawed page: no doctype,
lang, title or meta viewport; a head script delayed 300 ms by the server that busy-loops for 250 ms; a 4.8 MB uncompressed PNG with noalt, dimensions or cache headers; a 400 ms inline busy-loop; low-contrast text and an empty link and button. - Fixed page: all of those corrected, the script deferred (its busy-loop kept on purpose) and the image replaced by a 42.9 KB, 800 × 533 WebP with
alt, dimensions andfetchpriority="high".
Install and launch gotchas
| Step | Observed |
|---|---|
npm install [email protected], empty npm cache | 118 packages added in about 16 s, 0 vulnerabilities reported; node_modules 154.5 MB |
| Largest dependencies on disk | @sentry 31.0 MB plus a top-level sentry folder 21.4 MB, lighthouse 19.4 MB (registry unpackedSize 19,351,495 bytes, 982 files), @paulirish (trace engine) 16.3 MB, puppeteer-core 10.2 MB |
| CLI with no Chrome flags, as root | Failed after about 26 s: Running as root without --no-sandbox is not supported, surfaced as waiting for dynamic debugging port in chrome-err.log |
--chrome-flags="--no-sandbox" only | Failed the same way: The platform failed to initialize. Exiting. (no display) |
--chrome-flags="--headless" only | Failed: root sandbox error again |
--chrome-flags="--headless=new --no-sandbox" or "--headless --no-sandbox" | Both worked; every run below used --headless=new --no-sandbox |
| Chrome version in the LHR | Chrome/153.0.0.0 |
| Sentry prompt | Not shown (non-TTY); configstore file written with "isErrorReportingEnabled": false |
--list-all-audits | 166 audits; a default run executed 161 |
A root user in a display-less VM needs both a headless flag and --no-sandbox, and the error names the debugging port rather than the cause, which appears only in the echoed chrome-err.log. The variability doc says --no-sandbox and --headless "should be OK" for measurement.
Default mobile run, three times each
| Run | Perf | A11y | Best Pr. | SEO | Agentic | FCP | LCP | TBT | CLS | SI | Wall time |
|---|---|---|---|---|---|---|---|---|---|---|---|
| Flawed 1 | 48 | 28 | 85 | 75 | 50 | 1,835 ms | 24,451 ms | 1,409 ms | 0 | 2,223 ms | 12.0 s |
| Flawed 2 | 47 | 28 | 85 | 75 | 50 | 1,916 ms | 24,452 ms | 1,530 ms | 0 | 2,989 ms | 12.2 s |
| Flawed 3 | 48 | 28 | 85 | 75 | 50 | 1,830 ms | 24,452 ms | 1,418 ms | 0 | 2,233 ms | 11.9 s |
| Fixed 1 | 79 | 100 | 96 | 100 | 100 | 610 ms | 900 ms | 941 ms | 0 | 610 ms | 11.3 s |
| Fixed 2 | 79 | 100 | 96 | 100 | 100 | 608 ms | 901 ms | 952 ms | 0 | 608 ms | 11.7 s |
| Fixed 3 | 79 | 100 | 96 | 100 | 100 | 647 ms | 902 ms | 932 ms | 0 | 647 ms | 11.5 s |
Wall time covers the whole CLI process; the LHR's own timing.total was 6.6 to 7.4 s. Simulated throttling kept scores within one point across runs, and LCP, which is dominated by modelled transfer of the 4.8 MB image, varied by 1 ms. Speed Index moved the most, from 2,223 to 2,989 ms on the flawed page. The benchmarkIndex the report records for the host CPU swung from 1,523 to 2,480 between consecutive runs on the same VM, a concrete example of the "shared-core" noise the variability doc warns about.
On the flawed page, 29 scored audits came in below 0.9. The findings were specific: image-delivery-insight estimated 4,430 KiB of savings on hero.png, render-blocking-insight named blocking.js, lcp-discovery-insight asked for fetchpriority=high, color-contrast measured a 1.91 ratio, and the viewport, doctype, title, lang, alt and control-name checks failed as expected. Agentic Browsing scored 50 because agent-accessibility-tree failed; most of its other audits were "not applicable" on a page without WebMCP, llms.txt or an ARD manifest.
The fixed page still had six audits below 0.9, and they are instructive. TBT stayed around 940 ms because defer moves a script's work, it does not remove it: the 250 ms loop multiplied by the 4x CPU slowdown shows up as about 1 s of bootup-time. errors-in-console failed on a 404 for /favicon.ico, which the test server did not serve. document-latency-insight reported "No compression applied" because plain node:http sends uncompressed HTML; a web server configured for compression, such as Caddy, would clear that one. image-delivery-insight still suggested 13 KiB of savings because an 800-pixel image was displayed at 380 CSS pixels in the mobile viewport, and cache-insight noted that blocking.js had no cache lifetime.
Desktop preset and throttling methods
| Configuration | Page | Perf | FCP | LCP | TBT | SI | Wall time |
|---|---|---|---|---|---|---|---|
--preset=desktop | Flawed | 69 | 492 ms | 4,044 ms | 259 ms | 1,052 ms | 12.1 s |
--preset=desktop | Fixed | 96 | 174 ms | 240 ms | 176 ms | 210 ms | 11.6 s |
--throttling-method=provided | Flawed | 100 | 1,119 ms | 1,119 ms | 0 ms | 1,117 ms | 20.5 s |
--throttling-method=provided | Fixed | 97 | 93 ms | 102 ms | 204 ms | 101 ms | 20.1 s |
--throttling-method=devtools | Flawed | 64 | 1,981 ms | 26,746 ms | 0 ms | 10,775 ms | 49.1 s |
--throttling-method=devtools | Fixed | 97 | 688 ms | 1,519 ms | 202 ms | 1,186 ms | 21.6 s |
--only-categories=performance | Flawed | 48 | 1,893 ms | 24,510 ms | 1,393 ms | 2,876 ms | 11.8 s |
The provided rows matter most. With no throttling and a server on the same machine, the deliberately broken page scored a perfect 100 for performance: a 4.8 MB image crosses loopback almost instantly, and both busy-loops run before first paint, so they appear never to count towards Total Blocking Time. Accessibility and SEO scores were identical in every configuration; Best Practices on the flawed page rose from 85 to 88 under the desktop preset. The DevTools method scored the flawed page 64, again with TBT at 0, and took four times as long because the browser really waited for the throttled transfer. Simulated throttling was both the fastest and the harshest here.
Default JSON reports were 462 to 463 KB for the flawed page and 841 KB for the fixed one; the difference is mostly the fullPageScreenshot (22 KB versus 226 KB) and the screenshot-thumbnails audit (136 KB on the flawed page). --only-categories=performance cut the flawed report to 320 KB and 49 audits, though it saved almost no time. An HTML report of the fixed page was 952 KB. The new --url-file mode audited both pages in one 18.6 s process and wrote localhost-flawed.html_2026-11-18_13-39-57.report.html and localhost-fixed.html_..., confirming the path-based filenames from the 13.6.0 notes.
Node API and a user flow
| Test | Result |
|---|---|
Docs' Node example with chromeFlags: ['--headless=new', '--no-sandbox'], flawed page | Performance 48, returned keys lhr, artifacts (25 entries) and report (463 KB of HTML); 7.6 s including Chrome launch |
require('lighthouse') under Node 22.23 | Returns a module namespace object; the function is on .default, so the CommonJS example in docs/headless-chrome.md fails as written |
User flow via puppeteer-core (executablePath set, --no-sandbox): navigate, timespan with a click and an injected paragraph, snapshot, click-initiated navigation | 4 steps in 15.7 s; flow HTML 2.4 MB, flow JSON 2.1 MB |
| Navigation steps | 161 audits each, Performance 78 and 79 |
| Timespan step | 49 audits, CLS 0.037 from the injected paragraph, INP 40 ms, TBT 0 ms |
| Snapshot step | 90 audits, Accessibility, Best Practices, SEO and Agentic Browsing all 100 |
--only-categories=pwa | Runtime error encountered: unrecognized category in 'onlyCategories': pwa |
The user-flow docs import puppeteer, which Lighthouse does not install; it ships puppeteer-core 25.x, which needs an explicit browser path. One quirk: the timespan step's performance "score" was 100, computed only from TBT and CLS, and the snapshot step showed a performance score of 0 with no weighted audits behind it. The docs state that neither mode provides an overall performance score, so those fields are best ignored.
Lab data versus field data
Everything above is lab data: one synthetic load under a chosen device and network profile. The README's FAQ explains changing scores with "inherent variability in web and network technologies, even if there hasn't been a code change".
The variability doc lists the sources of noise and which throttling method mitigates each, recommends at least 2 dedicated cores and 2 GB of RAM, and warns against burstable instances and parallel runs. It states that "the median Lighthouse score of 5 runs is twice as stable as 1 run", and the Lantern doc gives a 95% confidence interval of plus or minus 15 points for one run of a median site, narrowing to plus or minus 8 with five runs.
Lighthouse does not collect real-user data; the README lists plugins such as lighthouse-plugin-field-performance and lighthouse-plugin-crux that pull Chrome UX Report data into a report. In the hands-on, one page scored 48, 64 or 100 depending only on the throttling method, and none of those numbers describes real visitors.
How Lighthouse compares
Facts below come from each project's README and npm entry, or the Lighthouse docs, as fetched on 18 November 2026; the alternatives were not run.
| Tool | What it is, per its sources | Relationship to Lighthouse | Licence | Best fit |
|---|---|---|---|---|
| Lighthouse CLI / Node | Local auditing of a page or user flow in Chrome | - | Apache-2.0 | Ad hoc audits, scripted checks, custom configs and plugins |
| PageSpeed Insights | Hosted service; the changelog says each Lighthouse release reaches it within days or weeks | Runs Lighthouse with the same simulated-throttling default, per the throttling doc | Hosted service (licence not applicable) | Quick checks of public URLs without local Chrome; a hosted service cannot reach a localhost build |
| WebPageTest | "performance-testing code that runs at webpagetest.org", with private instances and a REST API | Can add a Lighthouse report to its results (Lighthouse README); uses packet-level throttling | master branch Polyform Shield 1.0.0 (not OSI-approved); separate apache branch under Apache-2.0 | Real devices and locations, packet-level network shaping, waterfalls |
Lighthouse CI (@lhci/cli) | "a suite of tools that make continuously running, saving, retrieving, and asserting against Lighthouse results as easy as possible" | Official; 0.16.1 (11 November 2026) depends on lighthouse 13.6.0 | Apache-2.0 | Per-commit runs, assertions, budgets, a results server, multiple runs per URL |
| Unlighthouse | "scans your entire site using Google Lighthouse, with a modern UI, minimal config and smart sampling" | Wrapper that runs Lighthouse across many pages; README requires Node >= 22.18.0 | MIT (0.19.1, 3 October 2026) | Site-wide crawls rather than single pages |
| Chrome DevTools Performance panel | Trace recorder in Chrome; the architecture doc notes Lighthouse traces can be opened there | Complementary: same trace data, no scores | Part of Chrome | Investigating a specific slow interaction frame by frame |
| Playwright-based checks | General browser automation, see Playwright | Lighthouse documents only Puppeteer pages for flows; Playwright appears just in a warning about concurrent CDP control | Not covered here | Functional tests with custom timing or accessibility assertions |
For most teams the choice is not either-or. The variability doc itself recommends Lighthouse CI for collecting several runs and picking the median, and shows the commands:
npx -p @lhci/cli lhci collect --url https://example.com -n 5
npx -p @lhci/cli lhci upload --target filesystem --outputDir ./path/to/dump/reports
The Lighthouse CI getting-started guide runs Lighthouse three times per HTML file, uploads to "temporary public storage" unless configured otherwise, and shows chromeFlags: '--no-sandbox' for containers. When an AI coding agent needs to inspect a page during development, tools that expose DevTools to agents, such as Chrome DevTools MCP, sit closer to the Performance panel than to a scored audit. Lighthouse also needs Chrome or Chromium: the CLI help asks for "Chromium version 66.0 or later", so lightweight non-Chromium headless browsers such as Lightpanda are not a documented target.
Limits and when not to use it
- Scores depend on the method. The hands-on produced 48, 64 and 100 for one page under simulated, DevTools and provided throttling. Compare scores only across runs with identical settings, hardware and Lighthouse version.
- Localhost without throttling hides problems. The flawed page scored 100 under
providedthrottling. Keep the default simulated method for local checks, or use real network shaping. - Small cloud VMs and CI runners are noisy. The recorded
benchmarkIndexvaried by more than 60% between back-to-back runs on a 2-vCPU VM. The docs advise dedicated cores, no burstable instances and no parallel runs on one machine. - It does not replace field data. One lab load reflects a modelled device and network, not real visitors. Real-user metrics need CrUX, plugins that read it, or a RUM tool.
- Accessibility coverage is partial. A 100 means no automated rule failed, not that the page was reviewed with assistive technology.
- Root and containers need flags. As root Chrome needed
--no-sandbox, without a display a headless flag, and the headless guide warns that Docker's default 64 MB/dev/shmcan crash the tab unless--disable-dev-shm-usageor--shm-sizeis used. - Single-page apps need flows. Interactions and SPA transitions need timespan and snapshot steps scripted with Puppeteer, and those modes produce no performance score.
- Audit churn between majors. 13.0.0 removed a batch of audits in favour of insights, and the new Agentic Browsing category is labelled "still under development and subject to change". Scripts that read audit ids from the JSON need updating at each major version.
- Install weight and telemetry. About 154 MB of
node_modulesbefore Chrome, a third of it Sentry packages behind the CLI's opt-in error reporting. Interactive users are asked once; non-TTY andCIruns are never prompted, and the error-reporting doc says reports include the tested URL, OS and Chrome version. The Node module never reports.
Release cadence and documentation notes
The npm registry lists 149 stable versions plus nightly builds published under the next tag (the latest at the time of checking was 13.6.0-dev.20261117). After 13.0.0 (10 October 2025), npm shows 13.1.0 to 13.6.0 between April and October 2026, roughly one minor release every one to two months. The maintainers' release guide says they aim to bump the major version "no more than once a year" and follow semver.
A few documentation details are out of step with the 13.6.0 package. The CLI help in the README lists four categories for --only-categories, but a default run returned a fifth, agentic-browsing. The user-flows doc still lists "Assess Progressive Web App capabilities" as a navigation use case, while 13.6.0 rejects pwa as a category. The CommonJS example in docs/headless-chrome.md calls require('lighthouse') as a function, which does not work against the ESM package. The changelog dates 13.5.0 as 17 September 2026, while npm records its publication on 18 September. The installed package is more reliable than older doc snippets. Lighthouse audits whatever is rendered, so a site built with Svelte or any other framework gets the same checks.
Project activity
Checked 18 November 2026: latest release v13.6.0 (27 October 2026; v13.5.0 preceded it on 18 September 2026), Apache-2.0 licence, about 31,200 stars on the GoogleChrome/lighthouse repository (31,153 at the time of writing) with about 9,800 forks, and a push on the day of checking. The project is written in JavaScript, was created on 8 March 2016 and develops on the main branch. The changelog credits six new contributors in 13.6.0 alone. Documentation lives in the repository's docs/ folder and at developer.chrome.com; the official CI companion is Lighthouse CI.
Enjoying this project?
Discover more amazing open-source projects on TechLogHub. We curate the best developer tools and projects.
Repository:https://github.com/GoogleChrome/lighthouse
GitHub - GoogleChrome/lighthouse: Lighthouse: Web Performance and Accessibility Auditing
Lighthouse is Google Chrome's Apache-2.0 tool for auditing web performance, accessibility, SEO and best practices. v13.6.0 tested in a Linux VM on a flawed and ...
github - googlechrome/lighthouse
Related Projects
Maintain Lighthouse: Web Performance and Accessibility Auditing? Add the badge to your README
Show that the project is featured on TechLogHub and send readers to this write-up.
[](https://techloghub.com/open-source/lighthouse-web-auditing?utm_source=techloghub_badge&utm_medium=referral&utm_campaign=readme)