Lighthouse

Lighthouse is an open-source, automated tool for improving the quality of web pages. You can run it against any page on the web. It has audits for performance, accessibility, progressive web apps, and more.

You can run Lighthouse as a Chrome Extension, from the command line, or as a Node module. You give Lighthouse a URL to audit, it runs a series of audits against the page, and then it generates a report on how well the page did. From there, use the failing audits as indicators on how to improve the page. Each audit has a reference doc explaining why the audit is important, as well as how to fix it.

file_download Install Lighthouse bug_report File an issue

Get started

There are two primary ways to run Lighthouse: as a Chrome Extension, or as a command line tool. The Chrome Extension provides a more user-friendly interface for reading reports. The command line tool enables you to integrate Lighthouse into continuous integration systems.

Install and run the Chrome Extension

To install the extension:

  1. Download Google Chrome for Desktop.

  2. Install the Lighthouse Chrome Extension from the Chrome Webstore.

To run an audit:

  1. In Chrome, go to the page you want to audit.

  2. Click Lighthouse Lighthouse. It should be next to the Chrome address bar. If not, open Chrome's main menu and access it at the top of the menu. After clicking, the Lighthouse menu expands.

    The Lighthouse menu.
    Figure 1. The Lighthouse menu

  3. Click Generate report. Lighthouse runs its audits against the currently-focused page, then opens up a new tab with a report of the results.

    The Lighthouse menu.
    Figure 2. A Lighthouse report

Install and run the Node command line tool

To install the Node module:

  1. Download Google Chrome for Desktop.
  2. Install the current Long-Term Support version of Node.
  3. Install Lighthouse. The -g flag installs it as a global module.

    npm install -g lighthouse
    

To run an audit:

lighthouse <url>

To see audit options:

lighthouse --help

Run the Node module programmatically

See Using programmatically for an example of running Lighthouse programmatically, as a Node module.

Share and view reports online

Use the Lighthouse Viewer to view and share reports online.

The Lighthouse Viewer.
Figure 3. The Lighthouse Viewer

Share reports as JSON

The Lighthouse Viewer needs the JSON output of a Lighthouse report.

  • To get the JSON output of a report from the Chrome Extension version of Lighthouse, click Export > Save as JSON.
  • To get the JSON output of a report from the command line tool, run:

    lighthouse --output json --output-path <path/for/output.json>

To view the report data, open the Lighthouse Viewer in Chrome, and then drag the JSON file onto the viewer, or click anywhere on the Viewer to open your file navigator and select the file.

Share reports as GitHub Gists

If you don't want to manually pass around JSON files, you can also share your reports as secret GitHub Gists. One benefit of Gists is free version control.

To export a report as a Gist from the Chrome Extension version of Lighthouse:

  1. Click Export > Open In Viewer. The report opens in the Viewer, located at https://googlechrome.github.io/lighthouse/viewer/.
  2. In the Viewer, click Share Share. The first time you do this, a popup asks permission to access your basic GitHub data, and to read and write to your Gists.

To export a report as a Gist from the CLI version of Lighthouse, just manually create a Gist and copy-paste the report's JSON output into the Gist. See Share reports as JSON for an example of how to generate JSON output from the command line tool.

To view a report that's been saved as a Gist:

  • Add ?gist=<ID> to the Viewer's URL, where <ID> is the ID of the Gist.

    https://googlechrome.github.io/lighthouse/viewer/?gist=<ID>

  • Open the Viewer, and paste the URL of a Gist into it.

Contribute to Lighthouse

Lighthouse is open source and contributions are welcome. Check out the repository's issues tracker to find bugs that you can fix, or audits that you can create or improve upon. The issues tracker is also a good place to discuss audit metrics, ideas for new audits, or anything else related to Lighthouse.