{"canonical_url":"https://engineer.company/glossary/lighthouse/","content_markdown":"# Lighthouse\n\n## What it is\n\nLighthouse, often called Google Lighthouse, is an open-source program from the Chrome team that\nloads a single web page under controlled conditions, records what the browser did, and grades the\nresult out of 100 in four categories: performance, accessibility, best practices and SEO. It works\non any page it can reach, public or behind a login, and every check in its report links to a short\ndocument explaining why the check exists and how to pass it.\n\nThe same engine runs in four places:\n\n- in Chrome DevTools, from the Lighthouse panel;\n- on the command line, as `lighthouse \u003curl\u003e` after a global npm install;\n- as a Node module, inside a script of your own;\n- behind PageSpeed Insights, a Google service that runs it on Google's machines.\n\nThe performance score comes only from metrics measured during the load: First Contentful Paint,\nSpeed Index, Largest Contentful Paint, Total Blocking Time and Cumulative Layout Shift. Each metric\nis placed on a curve drawn from real websites in the HTTP Archive, and the category score is a\nweighted average of the five. In Lighthouse 10 the weights are 30% for Total Blocking Time, 25% each\nfor Largest Contentful Paint and Cumulative Layout Shift, and 10% each for the other two. They have\nchanged between versions, because the team keeps researching what most affects how fast a page\nfeels.\n\nThe curve has two fixed points. A metric value at the 25th percentile of the archive scores 50, and\none at the 8th percentile scores 90. Lower is better for every one of these metrics, so a page that\nscores 50 on one of them is already ahead of three quarters of the sites measured; 50 is not\naverage. Near the top the curve flattens: going from 99 to 100 takes about as much improvement as\ngoing from 90 to 94.\n\nThe other three categories are scored from audits instead. In accessibility, each audit passes or\nfails with no credit for a partial pass, each is weighted by the axe rule engine's assessment of how\nhard a failure hits users, and the checks that need a person are left out of the score and listed\nfor manual review.\n\n## Why it matters\n\nThe decision Lighthouse serves is whether a change made a page slower, harder to use or harder to\nfind, and whether that should stop it shipping. It answers in a form a machine can act on: a number,\nthe same audits every time and a report a script can parse. That makes it cheap enough to run on\nevery change rather than once before a launch.\n\nThe number is a laboratory measurement: one device profile, one simulated network, one load.\nPageSpeed Insights shows the difference by putting two kinds of data side by side. Its lab section\nis a Lighthouse run. Its field section comes from the Chrome UX Report: what real Chrome users\nexperienced over the previous 28 days, given at the 75th percentile so that the figure describes\nmost visitors rather than the luckiest. A page with too few visits of its own is shown with figures\nfor its whole origin. The documentation says to expect the two sections to differ.\n\nThat split decides what each is for. Field data says whether users have a problem, but it arrives\nweeks after a change and says nothing about a branch that has not shipped. Lab data can be collected\nbefore release and as often as needed, which makes it a guard, but it describes one simulated visit.\n\nThe other limit is noise. The scoring guide suggests reading performance “as a distribution of\nscores, rather than a single number”, and lists causes outside the page: A/B tests and rotating\nadverts, changes in internet routing, a fast desktop against a slow laptop, browser extensions and\nantivirus software. A threshold checked against one run will fail at random. The project's\nvariability guide gives the remedy a figure: the median of five runs is twice as stable as a single\nrun.\n\nLighthouse CI turns that into a rule. It runs Lighthouse several times per address, three by\ndefault, combines the runs and checks the result against assertions for a whole category or a single\naudit. An assertion at `warn` only reports; one at `error` fails the build. Its threshold is a\nminimum score, a maximum value for a metric or a maximum number of offending items:\n\n```json\n{\n    \"ci\": {\n        \"collect\": { \"numberOfRuns\": 5 },\n        \"assert\": {\n            \"assertions\": {\n                \"categories:accessibility\": [\"error\", { \"minScore\": 1 }],\n                \"largest-contentful-paint\": [\n                    \"error\",\n                    { \"maxNumericValue\": 2500, \"aggregationMethod\": \"median\" }\n                ]\n            }\n        }\n    }\n}\n```\n\n## What it looks like in practice\n\nThis site's [credits page](/credits/) lists Lighthouse among the tools the site runs against itself,\non the machine it is written on, and gives it one job: it holds the performance budgets. A budget is\na limit agreed in advance, so that a page that gets slower fails a check instead of starting an\nargument about whether a few hundred milliseconds matter.\n\nA later section of the same page links PageSpeed Insights among checks readers can run for\nthemselves, and says it runs Lighthouse from Google's machines rather than the site's, with\nreal-world data where enough people have visited. The page keeps the two apart on purpose. The first\nsection is the site marking its own homework; the second hands the same questions to tools that are\nnot the site's own and take nothing on its word.\n\nThe habit that makes a budget worth holding also shows in work here that has nothing to do with a\nscore. The account of how the\n[stylesheet bundle was cut from 87 KB to 31](/portfolio/cut-the-stylesheet-bundle-from-87-kb-to-31-kb/)\nopens its method with “Measurement first.” Two thirds of the largest stylesheet turned out to be one\nbase64-encoded font; a third font weight was preloaded only when field data showed it closing the\nlongest critical chain; and a modern image format for the brand mark was measured and declined,\nbecause it came out larger. Every decision there has a measurement attached, including the one that\nwent the other way. Lighthouse's suggestions need the same treatment: each is a hypothesis until a\nmeasurement says it helped.\n\n## Where it goes wrong\n\nMost Lighthouse mistakes come from reading the number as more than it is.\n\n**A single run is read as the truth.** One report shows 94, the next 87, and someone hunts a\nregression that never happened. Compare medians of several runs, and set the aggregation in\nLighthouse CI on purpose: an assertion written without options takes the value most likely to pass\nacross all runs, so a regression gets through as long as one run escapes it.\n\n**Runs are collected side by side.** Auditing ten addresses at once on one machine makes them\ncompete for processor, memory and network, and the variability guide says plainly not to do it. Run\nthem in turn, or across machines; for Lighthouse, more small machines beat one large one.\n\n**The lab score is read as what visitors get.** A 98 on a developer's laptop says the page can be\nfast; only field data says whether it was. Read the field section in PageSpeed Insights, and expect\na page with few visits to show its origin's figures.\n\n**The suggestions are treated as the score.** Opportunities and Diagnostics do not count towards the\nperformance score; they move it only through the metrics they improve. Pick the one that should move\na metric that matters for this page, make the change, and measure again.\n\n**A perfect score becomes the target.** The scoring guide calls 100 extremely challenging and says\nit is not expected. Once a page is in the green band, the last points cost more than they return.\n\n**A full accessibility score is read as an accessible page.** A 100 there means the automated audits\npassed. The manual checks are listed beside the score and never counted, so a page can score 100 and\nstill be impossible to use with a keyboard.\n\n## Further reading\n\n- [Introduction to Lighthouse](https://developer.chrome.com/docs/lighthouse/overview) — the ways to\n  run it, the categories it reports and where each audit's documentation lives.\n- [Lighthouse performance scoring](https://developer.chrome.com/docs/lighthouse/performance/performance-scoring)\n  — the metric weights by version, the scoring curves and the colour bands.\n- [Lighthouse accessibility score](https://developer.chrome.com/docs/lighthouse/accessibility/scoring)\n  — how audits are weighted and why manual checks stay out of the score.\n- [Score Variability](https://github.com/GoogleChrome/lighthouse/blob/main/docs/variability.md) —\n  the sources of noise, what reduces each one, and the case for running several times.\n- [About PageSpeed Insights](https://developers.google.com/speed/docs/insights/v5/about) — lab\n  against field data, the 75th percentile and the Core Web Vitals assessment.\n- [Lighthouse CI configuration](https://github.com/GoogleChrome/lighthouse-ci/blob/main/docs/configuration.md)\n  — collecting several runs, writing assertions and choosing how runs are combined.\n\n\u003chttps://engineer.company/glossary/lighthouse/\u003e\n","date_modified":"2026-10-20T21:59:50Z","description":"How Lighthouse turns one page load into four scores, why a single run is a sample rather than a verdict, and how a performance budget is held.","formats":{"gemtext":"https://engineer.company/glossary/lighthouse/index.gmi","gopher":"https://engineer.company/glossary/lighthouse/gophermap","html":"https://engineer.company/glossary/lighthouse/","json":"https://engineer.company/glossary/lighthouse/index.json","markdown":"https://engineer.company/glossary/lighthouse/index.md","pdf":"https://engineer.company/glossary/lighthouse/index.pdf"},"kind":"page","language":"en","title":"What is Lighthouse?","url":"https://engineer.company/glossary/lighthouse/","version":1}