Lighthouse: Web Performance and Accessibility Auditing
GitHub Repo
Apache-2.0
November 18, 2026 at 01:48 PM
0 views

Lighthouse: Web Performance and Accessibility Auditing

@GoogleChromeProject Author

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-mode saves the three main outputs: artifacts.json, trace.json (which "you can view in the DevTools Performance panel") and devtoolslog.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-size and others. Audits now have ids such as image-delivery-insight, render-blocking-insight and lcp-discovery-insight. 13.0.0 also made an unknown category in onlyCategories an 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-txt and 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 extend lighthouse:default.
  • Throttling control. Simulated, DevTools or provided throttling, with per-value flags such as --throttling.cpuSlowdownMultiplier and a benchmarkIndex in every report for calibrating CPU slowdown.
  • Machine-readable output. The LHR JSON carries each audit's score, numericValue and details, plus runtimeError for 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-headers and the chrome-debug binary.

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 no alt, 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 and fetchpriority="high".

Install and launch gotchas

StepObserved
npm install [email protected], empty npm cache118 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 rootFailed 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" onlyFailed the same way: The platform failed to initialize. Exiting. (no display)
--chrome-flags="--headless" onlyFailed: 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 LHRChrome/153.0.0.0
Sentry promptNot shown (non-TTY); configstore file written with "isErrorReportingEnabled": false
--list-all-audits166 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

RunPerfA11yBest Pr.SEOAgenticFCPLCPTBTCLSSIWall time
Flawed 148288575501,835 ms24,451 ms1,409 ms02,223 ms12.0 s
Flawed 247288575501,916 ms24,452 ms1,530 ms02,989 ms12.2 s
Flawed 348288575501,830 ms24,452 ms1,418 ms02,233 ms11.9 s
Fixed 17910096100100610 ms900 ms941 ms0610 ms11.3 s
Fixed 27910096100100608 ms901 ms952 ms0608 ms11.7 s
Fixed 37910096100100647 ms902 ms932 ms0647 ms11.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

ConfigurationPagePerfFCPLCPTBTSIWall time
--preset=desktopFlawed69492 ms4,044 ms259 ms1,052 ms12.1 s
--preset=desktopFixed96174 ms240 ms176 ms210 ms11.6 s
--throttling-method=providedFlawed1001,119 ms1,119 ms0 ms1,117 ms20.5 s
--throttling-method=providedFixed9793 ms102 ms204 ms101 ms20.1 s
--throttling-method=devtoolsFlawed641,981 ms26,746 ms0 ms10,775 ms49.1 s
--throttling-method=devtoolsFixed97688 ms1,519 ms202 ms1,186 ms21.6 s
--only-categories=performanceFlawed481,893 ms24,510 ms1,393 ms2,876 ms11.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

TestResult
Docs' Node example with chromeFlags: ['--headless=new', '--no-sandbox'], flawed pagePerformance 48, returned keys lhr, artifacts (25 entries) and report (463 KB of HTML); 7.6 s including Chrome launch
require('lighthouse') under Node 22.23Returns 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 navigation4 steps in 15.7 s; flow HTML 2.4 MB, flow JSON 2.1 MB
Navigation steps161 audits each, Performance 78 and 79
Timespan step49 audits, CLS 0.037 from the injected paragraph, INP 40 ms, TBT 0 ms
Snapshot step90 audits, Accessibility, Best Practices, SEO and Agentic Browsing all 100
--only-categories=pwaRuntime 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.

ToolWhat it is, per its sourcesRelationship to LighthouseLicenceBest fit
Lighthouse CLI / NodeLocal auditing of a page or user flow in Chrome-Apache-2.0Ad hoc audits, scripted checks, custom configs and plugins
PageSpeed InsightsHosted service; the changelog says each Lighthouse release reaches it within days or weeksRuns Lighthouse with the same simulated-throttling default, per the throttling docHosted 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 APICan add a Lighthouse report to its results (Lighthouse README); uses packet-level throttlingmaster branch Polyform Shield 1.0.0 (not OSI-approved); separate apache branch under Apache-2.0Real 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.0Apache-2.0Per-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.0MIT (0.19.1, 3 October 2026)Site-wide crawls rather than single pages
Chrome DevTools Performance panelTrace recorder in Chrome; the architecture doc notes Lighthouse traces can be opened thereComplementary: same trace data, no scoresPart of ChromeInvestigating a specific slow interaction frame by frame
Playwright-based checksGeneral browser automation, see PlaywrightLighthouse documents only Puppeteer pages for flows; Playwright appears just in a warning about concurrent CDP controlNot covered hereFunctional 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 provided throttling. Keep the default simulated method for local checks, or use real network shaping.
  • Small cloud VMs and CI runners are noisy. The recorded benchmarkIndex varied 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/shm can crash the tab unless --disable-dev-shm-usage or --shm-size is 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_modules before Chrome, a third of it Sentry packages behind the CLI's opt-in error reporting. Interactive users are asked once; non-TTY and CI runs 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.

Project
lighthouse-web-auditing
Created
November 18
Last Updated
November 18, 2026 at 01:48 PM

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.

Featured on TechLogHub
[![Featured on TechLogHub](https://techloghub.com/badge-neutral.svg)](https://techloghub.com/open-source/lighthouse-web-auditing?utm_source=techloghub_badge&utm_medium=referral&utm_campaign=readme)

Find more projects like this

One email a week: new and trending developer tools, fresh comparisons, and what shipped. Unsubscribe in one click.