lighthouse
Advanced tools
Lighthouse is an open-source, automated tool for improving the quality of web pages. It can be run against any web page, public or requiring authentication. It has audits for performance, accessibility, progressive web apps, SEO, and more.
Performance Audits
This feature allows you to run performance audits on a web page. The code sample demonstrates how to launch a headless Chrome instance, run Lighthouse against a URL, and log the performance score.
const lighthouse = require('lighthouse');
const chromeLauncher = require('chrome-launcher');
(async () => {
const chrome = await chromeLauncher.launch({chromeFlags: ['--headless']});
const options = {logLevel: 'info', output: 'json', onlyCategories: ['performance'], port: chrome.port};
const runnerResult = await lighthouse('https://example.com', options);
console.log('Report is done for', runnerResult.lhr.finalUrl);
console.log('Performance score was', runnerResult.lhr.categories.performance.score * 100);
await chrome.kill();
})();Accessibility Audits
This feature allows you to run accessibility audits on a web page. The code sample demonstrates how to launch a headless Chrome instance, run Lighthouse against a URL, and log the accessibility score.
const lighthouse = require('lighthouse');
const chromeLauncher = require('chrome-launcher');
(async () => {
const chrome = await chromeLauncher.launch({chromeFlags: ['--headless']});
const options = {logLevel: 'info', output: 'json', onlyCategories: ['accessibility'], port: chrome.port};
const runnerResult = await lighthouse('https://example.com', options);
console.log('Report is done for', runnerResult.lhr.finalUrl);
console.log('Accessibility score was', runnerResult.lhr.categories.accessibility.score * 100);
await chrome.kill();
})();SEO Audits
This feature allows you to run SEO audits on a web page. The code sample demonstrates how to launch a headless Chrome instance, run Lighthouse against a URL, and log the SEO score.
const lighthouse = require('lighthouse');
const chromeLauncher = require('chrome-launcher');
(async () => {
const chrome = await chromeLauncher.launch({chromeFlags: ['--headless']});
const options = {logLevel: 'info', output: 'json', onlyCategories: ['seo'], port: chrome.port};
const runnerResult = await lighthouse('https://example.com', options);
console.log('Report is done for', runnerResult.lhr.finalUrl);
console.log('SEO score was', runnerResult.lhr.categories.seo.score * 100);
await chrome.kill();
})();Progressive Web App (PWA) Audits
This feature allows you to run Progressive Web App (PWA) audits on a web page. The code sample demonstrates how to launch a headless Chrome instance, run Lighthouse against a URL, and log the PWA score.
const lighthouse = require('lighthouse');
const chromeLauncher = require('chrome-launcher');
(async () => {
const chrome = await chromeLauncher.launch({chromeFlags: ['--headless']});
const options = {logLevel: 'info', output: 'json', onlyCategories: ['pwa'], port: chrome.port};
const runnerResult = await lighthouse('https://example.com', options);
console.log('Report is done for', runnerResult.lhr.finalUrl);
console.log('PWA score was', runnerResult.lhr.categories.pwa.score * 100);
await chrome.kill();
})();Web Vitals is a library for measuring essential metrics that are critical to delivering a great user experience on the web. It focuses on metrics like Largest Contentful Paint (LCP), First Input Delay (FID), and Cumulative Layout Shift (CLS). Unlike Lighthouse, which provides a comprehensive audit, Web Vitals focuses specifically on user-centric performance metrics.
Axe-core is a JavaScript library that helps developers find and fix accessibility issues in their web applications. It is highly focused on accessibility audits, whereas Lighthouse provides a broader range of audits including performance, SEO, and PWA.
PSI (PageSpeed Insights) is a tool that provides insights into how well a page performs on both mobile and desktop devices. It uses Lighthouse under the hood but is more focused on providing actionable insights for performance improvements. PSI is more user-friendly and less customizable compared to running Lighthouse directly.
Lighthouse analyzes web apps and web pages, collecting modern performance metrics and insights on developer best practices.
Lighthouse requires Chrome stable or later.
Lighthouse is integrated directly into the Chrome Developer Tools, under the "Audits" panel.
Installation: install Chrome Canary.
Run it: open Chrome DevTools, select the Audits panel, and hit "Perform an Audit...".
Installation: install the extension from the Chrome Web Store.
Run it: follow the extension quick-start guide.
Lighthouse requires Node 6 or later.
Installation:
npm install -g lighthouse
# or use yarn:
# yarn global add lighthouse
Run it: lighthouse https://airhorner.com/
By default, Lighthouse writes the report to an HTML file. You can control the output format by passing flags.
$ lighthouse --help
lighthouse <url>
Logging:
--verbose Displays verbose logging [boolean]
--quiet Displays no progress, debug logs or errors [boolean]
Configuration:
--save-assets Save the trace contents & screenshots to disk [boolean]
--save-artifacts Save all gathered artifacts to disk [boolean]
--list-all-audits Prints a list of all available audits and exits [boolean]
--list-trace-categories Prints a list of all required trace categories and exits [boolean]
--additional-trace-categories Additional categories to capture with the trace (comma-delimited).
--config-path The path to the config JSON.
--chrome-flags Custom flags to pass to Chrome (space-delimited). For a full list of flags, see
http://peter.sh/experiments/chromium-command-line-switches/. [default: ""]
--perf Use a performance-test-only configuration [boolean]
--port The port to use for the debugging protocol. Use 0 for a random port [default: 9222]
--max-wait-for-load The timeout (in milliseconds) to wait before the page is considered done loading and the run should continue.
WARNING: Very high values can lead to large traces and instability [default: 25000]
Output:
--output Reporter for the results, supports multiple values [choices: "json", "html", "domhtml"] [default: "html"]
--output-path The file path to output the results. Use 'stdout' to write to stdout.
If using JSON output, default is stdout.
If using HTML output, default is a file in the working directory with a name based on the test URL and date.
If using multiple outputs, --output-path is ignored.
Example: --output-path=./lighthouse-results.html
--view Open HTML report in your browser [boolean]
Options:
--help Show help [boolean]
--version Show version number [boolean]
--disable-storage-reset Disable clearing the browser cache and other storage APIs before a run [boolean]
--disable-device-emulation Disable Nexus 5X emulation [boolean]
--disable-cpu-throttling Disable CPU throttling [boolean] [default: false]
--disable-network-throttling Disable network throttling [boolean]
--skip-autolaunch Skip autolaunch of Chrome when already running instance is not found [boolean]
--select-chrome Interactively choose version of Chrome to use when multiple installations are found [boolean]
--interactive Open Lighthouse in interactive mode [boolean]
Examples:
lighthouse <url> --view Opens the HTML report in a browser after the run completes
lighthouse <url> --config-path=./myconfig.js Runs Lighthouse with your own configuration: custom audits, report
generation, etc.
lighthouse <url> --output=json --output-path=./report.json --save-assets Save trace, screenshots, and named JSON report.
lighthouse <url> --disable-device-emulation --disable-network-throttling Disable device emulation
lighthouse <url> --chrome-flags="--window-size=412,732" Launch Chrome with a specific window size
lighthouse <url> --quiet --chrome-flags="--headless" Launch Headless Chrome, turn off logging
For more information on Lighthouse, see https://developers.google.com/web/tools/lighthouse/.
lighthouse generates
./<HOST>_<DATE>.report.htmllighthouse --output json generates
stdoutlighthouse --output html --output-path ./report.html generates
./report.htmlNOTE: specifying an output path with multiple formats ignores your specified extension for ALL formats
lighthouse --output json --output html --output-path ./myfile.json generates
./myfile.report.json./myfile.report.htmllighthouse --output json --output html generates
./<HOST>_<DATE>.report.json./<HOST>_<DATE>.report.htmllighthouse --output-path=~/mydir/foo.out --save-assets generates
~/mydir/foo.report.html~/mydir/foo-0.trace.json~/mydir/foo-0.screenshots.htmllighthouse --output-path=./report.json --output json --save-artifacts generates
./report.json./report.artifacts.loglighthouse --save-artifacts generates
./<HOST>_<DATE>.report.html./<HOST>_<DATE>.artifacts.logLighthouse can produce a report as JSON or HTML.
HTML report:
Running Lighthouse with the --output=json flag generates a json dump of the run.
You can view this report online by visiting https://googlechrome.github.io/lighthouse/viewer/
and dragging the file onto the app. You can also use the "Export" button from the
top of any Lighthouse HTML report and open the report in the
Lighthouse Viewer.
In the Viewer, reports can be shared by clicking the share icon in the top right corner and signing in to GitHub.
Note: shared reports are stashed as a secret Gist in GitHub, under your account.
Useful documentation, examples, and recipes to get you started.
Docs
Recipes
Videos
The session from Google I/O 2017 covers architecture, writing custom audits, Github/Travis/CI integration, headless Chrome, and more:
click to watch the video
Read on for the basics of hacking on Lighthouse. Also see Contributing for detailed information.
# yarn should be installed first
git clone https://github.com/GoogleChrome/lighthouse
cd lighthouse
yarn
yarn install-all
yarn build-all
# The CLI and Chrome Launcher are authored in TypeScript and require compilation.
# If you need to make changes to the CLI, run the TS compiler in watch mode:
# cd lighthouse-cli && yarn dev
# similarly, run the TS compiler for the launcher:
# cd chrome-launcher && yarn dev
node lighthouse-cli http://example.com
Getting started tip:
node --inspect --debug-brk lighthouse-cli http://example.comto open up Chrome DevTools and step through the entire app. See Debugging Node.js with Chrome DevTools for more info.
# lint and test all files
yarn test
# watch for file changes and run tests
# Requires http://entrproject.org : brew install entr
yarn watch
## run linting, unit, and smoke tests separately
yarn lint
yarn unit
yarn smoke
## run closure compiler (on whitelisted files)
yarn closure
## import your report renderer into devtools-frontend and run devtools closure compiler
yarn compile-devtools
Calibre - Calibre is a web performance monitoring tool running Lighthouse continuously or on-demand via an API. Test using emulated devices and connection speeds from a number of geographical locations. Set budgets and improve performance with actionable guidelines.
Web Page Test — An open source tool for measuring and analyzing the performance of web pages on real devices. Users can choose to produce a Lighthouse report alongside the analysis of WebPageTest results.
Do Better Web is an initiative within Lighthouse to help web developers modernize their existing web applications. By running a set of tests, developers can discover new web platform APIs, become aware of performance pitfalls, and learn (newer) best practices. In other words, do better on the web!
DBW is implemented as a set of standalone gatherers and audits that are run alongside the core Lighthouse tests. The tests show up under "Best Practices" in the report.
If you'd like to contribute, check the list of issues or propose a new audit by filing an issue.
Nope. Lighthouse runs locally, auditing a page using a local version of the Chrome browser installed the machine. Report results are never processed or beaconed to a remote server.
Tip: see Lighthouse Architecture for more information on terminology and architecture.
Lighthouse can be extended to run custom audits and gatherers that you author. This is great if you're already tracking performance metrics in your site and want to surface those metrics within a Lighthouse report.
If you're interested in running your own custom audits, check out our Custom Audit Example over in recipes.
We'd love help writing audits, fixing bugs, and making the tool more useful! See Contributing to get started.
Lighthouse, ˈlītˌhous (n): a tower or other structure tool containing a beacon light
to warn or guide ships at sea developers.
12.2.1 (2024-09-06)
We expect this release to ship in the DevTools of Chrome 130, and to PageSpeed Insights within 2 weeks.
<a name="12.2.0"></a>
FAQs
Automated auditing, performance metrics, and best practices for the web.
The npm package lighthouse receives a total of 1,014,672 weekly downloads. As such, lighthouse popularity was classified as popular.
We found that lighthouse demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 4 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
Fluent Assertions is facing backlash after dropping the Apache license for a commercial model, leaving users blindsided and questioning contributor rights.
Research
Security News
Socket researchers uncover the risks of a malicious Python package targeting Discord developers.
Security News
The UK is proposing a bold ban on ransomware payments by public entities to disrupt cybercrime, protect critical services, and lead global cybersecurity efforts.