Choose the run before admiring the report. Lighthouse analyzes web pages and web apps, collecting performance metrics and insights about developer best practices. It can produce useful evidence about accessibility, performance, SEO and general site quality. An HTML report is still exquisitely formatted homework, not proof that the website is finished.

The documented CLI categories are accessibility, best-practices, performance and seo. PWA testing was deprecated, and pwa is not among the current CLI category choices. Notice what is also missing: there is no security category. Individual best-practices audits may concern security-related behaviour, but the category name does not turn Lighthouse into a security assessment with a jaunty green badge.

Lighthouse is available through Chrome DevTools, the older Chrome extension, the Node CLI and a Node module. DevTools suits an immediate inspection. The CLI exposes the configuration and output controls needed for repeatable or automated runs. The project documentation describes the CLI as the flexible option for advanced and automated use.

A run is collection followed by judgement

The CLI exposes Lighthouse's two-stage design unusually clearly. --gather-mode, also written -G, collects artifacts from a connected browser and saves them to disk. If audit mode is not enabled as well, Lighthouse stops after collection. --audit-mode, or -A, processes previously saved artifacts, using ./latest-run/ when no artifact path is supplied.

This separation is useful when collection is expensive, awkward or tied to a particular browser state. The same captured artifacts can be audited without immediately driving the browser again. It also explains a common mystery: gathering successfully is not the same operation as generating a report. The command did exactly what it was told, which remains one of computing's less comforting achievements.

With --save-assets, Lighthouse saves trace contents and DevTools logs. The CLI can also list every available audit with --list-all-audits, or list required trace categories with --list-trace-categories. --additional-trace-categories adds comma-delimited categories to the capture when a specialised investigation needs more than the standard trace.

Browser control happens through the debugging protocol. --port selects its port, with 0 requesting a random one, while --hostname defaults to localhost. --chrome-flags passes custom flags to Chrome. The documented CHROME_PATH environment variable selects a particular Chrome binary; otherwise Lighthouse uses a detected Chrome Canary or stable installation.

Pick the smallest interface that answers the question

In Chrome DevTools, open the Lighthouse panel and select "Generate report." This is the shortest route from a suspicious page to a report, and it avoids maintaining a separate global CLI installation. It is particularly suitable when the real task is inspecting one page during development rather than constructing an automated reporting pipeline.

The Chrome extension predates the DevTools integration and offers similar functionality. Its continued existence is less a mystery than a small archaeological layer in the browser toolbar. Installation and operation are documented in the extension quick-start guide.

For CLI use, the README gives these commands:


npm install -g lighthouse


lighthouse https://airhorner.com/

The package is published as lighthouse on npm. By default, a CLI run writes an HTML report. Available output formats are HTML, JSON and CSV, and --output accepts multiple values. JSON defaults to standard output, while HTML and CSV default to files named from the tested URL and date.

Use --output-path when another process needs a predictable location. With multiple formats, Lighthouse appends the standard report extension to the supplied base path. For example, the documented base reports/my-run becomes files such as reports/my-run.report.html and reports/my-run.report.json. --view opens an HTML report in the browser after generation.

Configuration is part of the result

Lighthouse can run only selected audits with --only-audits, only selected categories with --only-categories, or everything except named audits with --skip-audits. Narrowing a run is useful, but the resulting report says nothing about audits that were excluded. A performance-only report is not a suspiciously concise accessibility report. It simply never applied for that job.

Built-in --preset choices are perf, experimental and desktop. A custom --config-path takes precedence: when both are supplied, the preset is ignored. This is easy to miss because both arguments remain visible in the command, standing beside each other like colleagues who have agreed never to communicate.

For desktop testing, the CLI help specifically directs users to --preset=desktop. --form-factor controls scoring parameters and whether mobile-only audits are skipped, but the documentation still points desktop runs toward the preset. Screen emulation can instead be disabled or configured through its mobile, width, height and device-scale-factor settings.

My working rule is to record the preset, audit filters, throttling method, storage-reset choice, locale and Chrome selection beside every retained report. Otherwise two reports can have the same URL and materially different configurations, leaving the comparison to be settled by interpretive dance.

Lighthouse normally clears browser cache and other storage APIs before a run; --disable-storage-reset prevents that clearing. It also normally collects a full-page screenshot, which can be large; --disable-full-page-screenshot turns that collection off. Those are not housekeeping details. They determine what state and evidence the run contains.

--max-wait-for-load controls how long Lighthouse waits before treating page loading as complete. The CLI warns that very high values can produce large traces and instability. --blocked-url-patterns blocks matching network requests, while --locale controls the report language. Each changes the question being asked, so each belongs with the saved result.

Read the evidence at its actual scope

The documented pipeline captures artifacts from a connected browser and audits those artifacts. The resulting performance evidence therefore describes that run and its configuration. The supplied documentation does not describe the report as field telemetry gathered from a population of real visitors, so it should not be labelled that way.

Likewise, an accessibility category result is the outcome of the accessibility audits that actually ran. It is not, merely by existing, a blanket accessibility-conformance certificate. Check which audits were included, inspect individual findings and retain manual assessment for requirements that the report does not claim to evaluate.

The same restraint applies to seo and best-practices. Those names identify groups of audits, not promises about search placement, complete security coverage or overall production readiness. Lighthouse reports concrete findings. The interpretive inflation usually arrives later, often in a spreadsheet wearing a tie.

For diagnosis, --verbose displays verbose logging. --quiet suppresses progress, debug logs and errors, so it is a poor companion when the immediate problem is that the run itself is failing. Error reporting can be explicitly enabled or disabled with --enable-error-reporting and its negative form; the project maintains separate error-reporting documentation.

Where Lighthouse goes sideways

The report looks mobile when desktop was intended

Symptom: Layout, emulation or audit coverage does not match the intended desktop run.

Cause: The run did not use --preset=desktop, or a supplied --config-path caused that preset to be ignored.

What to do: Use the documented desktop preset and check for a custom configuration path. If both appear, inspect the custom configuration because it wins.

Gathering finishes but no report appears

Symptom: Browser artifacts are written successfully, yet no HTML, JSON or CSV report is produced.

Cause: --gather-mode collects and saves artifacts, then quits early unless audit mode is also enabled.

What to do: Include audit mode when both stages should happen together, or subsequently process the saved artifact directory with --audit-mode.

An expected category or audit has disappeared

Symptom: A report lacks accessibility, performance, SEO or best-practices findings that another run contained.

Cause: --only-categories, --only-audits or --skip-audits narrowed the run.

What to do: Review the audit and category filters, then use --list-all-audits to verify the available audit names.

A preset appears to have no effect

Symptom: --preset=desktop, --preset=perf or --preset=experimental is present, but behaviour follows another configuration.

Cause: --config-path was also provided. The CLI explicitly ignores the preset in that case.

What to do: Remove the competing input or move the intended settings into the custom configuration. Do not debug the preset while another file is holding the steering wheel.

Cached or stored state leaks into the run

Symptom: The tested page reflects retained browser cache or other storage state when a clean run was expected.

Cause: --disable-storage-reset prevented Lighthouse from clearing those stores before collection.

What to do: Remove the flag for a reset run. When retained state is deliberate, record that choice with the report so the result is not mistaken for a clean-state measurement.

The trace becomes enormous or the run turns unstable

Symptom: Collection produces an unexpectedly large trace or becomes unstable while waiting for page loading.

Cause: --max-wait-for-load was set very high. The CLI documentation warns about both consequences.

What to do: Reduce the timeout to the smallest value that still represents the intended loading scenario, then investigate why the page needs additional time rather than granting it geological eras.

Output lands somewhere unexpected

Symptom: No obvious HTML file appears, JSON arrives on standard output, or multiple reports have extensions added to the requested path.

Cause: Output behaviour differs by format. JSON defaults to standard output; HTML and CSV default to generated filenames. Multiple outputs append their standard extensions to the --output-path base.

What to do: Set both --output and --output-path explicitly, then make downstream automation consume the resulting format-specific filenames.

References

Important notice. Tap any item to read it in full.

Accuracy is not guaranteed

This article was produced with substantial automated assistance and is published without individual expert verification of every statement. It may contain errors, omissions, oversimplifications, or claims that were accurate when written and have since been superseded. Software, protocols, specifications and best practice in this field change quickly.

Verify before you rely on it

Treat this page as a starting point and a pointer to primary sources, never as an authority in itself. Before acting on anything here, check it against the official documentation, the original publication, or the vendor's own materials, which are linked in the references above. Where this page and a primary source disagree, the primary source is correct and this page is wrong.

No warranty

This content is provided "as is", without warranty of any kind, express or implied, including but not limited to warranties of accuracy, completeness, currency, merchantability, or fitness for a particular purpose.

No liability

To the fullest extent permitted by applicable law, scoutb2.io and its authors accept no liability for any loss or damage whatsoever, whether direct, indirect, incidental, consequential or otherwise, arising from use of or reliance on this article. This expressly includes lost time, lost data, damaged samples or specimens, wasted reagents or compute, failed experiments, equipment damage, and commercial loss.

Not professional advice

Nothing here constitutes professional, scientific, engineering, regulatory, safety or legal advice. You remain solely responsible for your own experimental design, safety assessment, regulatory compliance and data handling, and for any code you run or procedure you perform.

About the illustration

Any image accompanying this article is editorial and decorative. It was produced with generative AI, is not a technical diagram, is not to scale, and is not an accurate depiction of any structure, process or result. Do not read measurements, structures or relationships from it.

Third-party names and links

Product, project and organisation names are the property of their respective owners and are used for identification only. Their mention is not endorsement, affiliation or sponsorship in either direction. External links are provided for convenience and we neither control nor are responsible for third-party content.

Corrections

If you find an error, tell us and we will correct or withdraw the page.

Lighthouse finds browser evidence, not a verdict on your website