lighthouse Documentation

File: README.md

Lighthouse [](https://github.com/GoogleChrome/lighthouse/actions/workflows/ci.yml) [](https://github.com/GoogleChrome/lighthouse/actions/workflows/unit.yml) [](https://github.com/GoogleChrome/lighthouse/actions/workflows/smoke.yml) [](https://codecov.io/gh/GoogleChrome/lighthouse) [](https://lh-build-tracker.herokuapp.com/) [](https://npmjs.org/package/lighthouse)

Lighthouse analyzes web apps and web pages, collecting modern performance metrics and insights on developer best practices.

Using Lighthouse
Associated Products and Projects
FAQ

Using Lighthouse in Chrome DevTools

Lighthouse is integrated directly into the Chrome DevTools, under the "Lighthouse" panel.

Installation: install Chrome.

Run it: open Chrome DevTools, select the Lighthouse panel, and hit "Generate report".

Using the Chrome extension

The Chrome extension was available prior to Lighthouse being available in Chrome Developer Tools, and offers similar functionality.

Installation: install the extension from the Chrome Web Store.

Run it: follow the extension quick-start guide.

Using the Node CLI

The Node CLI provides the most flexibility in how Lighthouse runs can be configured and reported. Users who want more advanced usage, or want to run Lighthouse in an automated fashion should use the Node CLI.

[!NOTE]
Lighthouse requires Node 22 (LTS) or later.

Installation:

npm install 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.

CLI options

text

/* Detailed source-code truncated for AI context efficiency. */

Output Examples

lighthouse
# saves `./<HOST>_<DATE>.report.html`

lighthouse --output json
# json output sent to stdout

lighthouse --output html --output-path ./report.html
# saves `./report.html`

# NOTE: specifying an output path with multiple formats ignores your specified extension for *ALL* formats
lighthouse --output json --output html --output-path ./myfile.json
# saves `./myfile.report.json` and `./myfile.report.html`

lighthouse --output json --output html
# saves `./<HOST>_<DATE>.report.json` and `./<HOST>_<DATE>.report.html`

lighthouse --output-path=~/mydir/foo.out --save-assets
# saves `~/mydir/foo.report.html`
# saves `~/mydir/foo-0.trace.json` and `~/mydir/foo-0.devtoolslog.json`

lighthouse --output-path=./report.json --output json
# saves `./report.json`

Lifecycle Examples

You can run a subset of Lighthouse's lifecycle if desired via the --gather-mode (-G) and --audit-mode (-A) CLI flags.

lighthouse http://example.com -G
# launches browser, collects artifacts, saves them to disk (in `./latest-run/`) and quits

lighthouse http://example.com -A
# skips browser interaction, loads artifacts from disk (in `./latest-run/`), runs audits on them, generates report

lighthouse http://example.com -GA
# Normal gather + audit run, but also saves collected artifacts to disk for subsequent -A runs.


# You can optionally provide a custom folder destination to -G/-A/-GA. Without a value, the default will be `$PWD/latest-run`.
lighthouse -GA=./gmailartifacts https://gmail.com

Notes on Error Reporting

The first time you run the CLI you will be prompted with a message asking you if Lighthouse can anonymously report runtime exceptions. The Lighthouse team uses this information to detect new bugs and avoid regressions. Opting out will not affect your ability to use Lighthouse in any way. Learn more.

Using the Node module

You can also use Lighthouse programmatically with the Node module.

Read Using Lighthouse programmatically for help getting started.
Read Lighthouse Configuration to learn more about the configuration options available.

Viewing a report

Lighthouse can produce a report as JSON or HTML.

HTML report:

Online Viewer

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.

Docs & Recipes

Useful documentation, examples, and recipes to get you started.

Docs

Recipes

Plugin - example Lighthouse plugin
Custom Audit example - extend Lighthouse, run your own audits

Videos

The session from Google I/O 2018 covers the new performance engine, upcoming Lighthouse REST API, and using the Chrome UX report to evaluate real-user data.

The session from Google I/O 2017 covers architecture, writing custom audits,
GitHub/Travis/CI integration, headless Chrome, and more:

Click the image to watch the video on YouTube.

Develop

Read on for the basics of hacking on Lighthouse. Also, see Contributing
for detailed information.

Setup

# yarn should be installed first

git clone https://github.com/GoogleChrome/lighthouse

cd lighthouse
yarn
yarn build-all

Run

node cli http://example.com
# append --chrome-flags="--no-sandbox --headless --disable-gpu" if you run into problems connecting to Chrome

Getting started tip: node --inspect-brk cli http://example.com to open up Chrome DevTools and step
through the entire app. See Debugging Node.js with Chrome
DevTools
for more info.

Tests

# lint and test all files
yarn test

# run all unit tests
yarn unit

# run a given unit test (e.g. core/test/audits/byte-efficiency/uses-long-cache-ttl-test.js)
yarn mocha uses-long-cache-ttl

# 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 tsc compiler
yarn type-check

Docs

Some of our docs have tests that run only in CI by default. To modify our documentation, you'll need to run yarn build-pack && yarn test-docs locally to make sure they pass.

Additional Dependencies

brew install jq

Lighthouse Integrations in Web Perf services

This section details services that have integrated Lighthouse data. If you're working on a cool project integrating Lighthouse and would like to be featured here, file an issue to this repo or tweet at us @_____lighthouse!

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.
HTTPArchive - HTTPArchive tracks how the web is built by crawling 500k pages with Web Page Test, including Lighthouse results, and stores the information in BigQuery where it is publicly available.
Calibre - Calibre is a comprehensive performance monitoring platform running on Lighthouse. See the performance impact of your work before it hits production with GitHub Pull Request Reviews. Track the impact of Third Party scripts. Automate your performance system with a developer-first Node.js API. Try Calibre with a free 15-day trial.
DebugBear - DebugBear is a website monitoring tool based on Lighthouse. See how your scores and metrics changed over time, with a focus on understanding what caused each change. DebugBear is a paid product with a free 30-day trial.
Treo - Treo is Lighthouse as a Service. It provides regression testing, geographical regions, custom networks, and integrations with GitHub & Slack. Treo is a paid product with plans for solo-developers and teams.
PageVitals - PageVitals combines Lighthouse, CrUX and field testing to monitor the performance of websites. See how your website performs over time and get alerted if it gets too slow. Drill down and find the real cause of any performance issue. PageVitals is a paid product with a free 14-day trial.
Screpy - Screpy is a web analysis tool that can analyze all pages of your websites in one dashboard and monitor them with your team. It's powered by Lighthouse and it also includes some different analysis tools (SERP, W3C, Uptime, etc). Screpy has free and paid plans.
Siteimprove Performance — Siteimprove Performance is a web Performance monitoring solution that enables a marketer, manager or decision maker to understand and optimize website load times. Get easy-to-use insights with a focus on quick and impactful wins. Siteimprove Performance is a paid product with a free 14-day trial.
SpeedCurve — SpeedCurve is a tool for continuously monitoring web performance across different browsers, devices, and regions. It can aggregate any metric including Lighthouse scores across multiple pages and sites, and allows you to set performance budgets with Slack or email alerts. SpeedCurve is a paid product with a free 30-day trial.
Foo - Lighthouse-as-a-service offering free and premium plans. Provides monitoring and historical reporting of Lighthouse audits with CircleCI, GitHub, and other integrations. Features include Slack notifications, PR comment reporting and more.
Apdex - Apdex is a website performance service. The main features are historical Lighthouse report visualizations, mobile/desktop options, alerts, uptime monitoring, and more. There are flexible paid plans and a 30-day free trial.
Websu - Websu is an open source project to provide Lighthouse-as-a-Service through a simple HTTP REST API. The main features are ability to host and deploy in your own environment and historical Lighthouse report summaries.
DTEKT.IO - DTEKT is a website performance and uptime monitoring service. It uses lighthouse to provide visibility into the performance of websites from multiple locations on multiple devices. It offers three months free trial and paid plans.
SpeedVitals - SpeedVitals is a Lighthouse powered tool to measure web performance across multiple devices and locations. It has various features like Layout Shift Visualization, Waterfall Chart, Field Data and Resource Graphs. SpeedVitals offers both free and paid plans.
Lighthouse Metrics - Lighthouse Metrics gives you global performance insights with a single test. You can also monitor your websites on a daily or hourly base. Lighthouse Metrics offers free global one-time tests and performance monitoring as a paid feature with a free 14-day trial.
Auditzy - Auditzy™ is a robust website auditing & monitoring tool which lets you analyze your web page(s) pre-user journey. Analyze the Competitor Health Metric, Core Web Vitals, and Technology. Compare your web pages with your competitors to understand where you are leading or lagging. Real-time notification with Slack. Have Seamless Collaboration with Multiple Teams. Automate your Audits hourly, daily, weekly, and so on. It has a free trial with pay as you go plans.
Lighthouse Metrics China - The first Lighthouse metrics tool specifically designed for China. Experience unparalleled website monitoring capabilities with Lighthouse. Gain insights into the fluctuations of your scores and metrics within the realm of the Great Firewall of China, enabling a comprehensive understanding of the factors influencing each change. Lighthouse Metrics China offers both free and paid plans.
DeploymentHawk - DeploymentHawk is an automated site auditing tool powered by Lighthouse. Effortlessly catch performance, accessibility, and SEO issues before they impact your users. DeploymentHawk is a paid product with a free 7-day trial.
Guardius - Guardius is a DevOps and DevSecOps SaaS platform that integrates Lighthouse to deliver automated web performance analysis. It not only provides metrics evaluation and automatic scanning but also enables performance comparisons across different periods and ongoing observation over time. Additionally, Guardius offers predefined and customized alerts tailored to your specific requirements. A free version of Guardius is available for users to explore its features.
Sonā - Powered by Lighthouse amongst others, Sonā delivers in-depth insights into your website’s health. Track changes over time, share reports, and receive actionable recommendations to improve performance, accessibility, SEO, best practices, and security. Sonā is free during its beta period.
FERU - Run Google Lighthouse speed tests from multiple regions worldwide. Lighthouse scores, Core Web Vitals, and mobile performance metrics to easily test your site's speed, accessibility, and SEO. FERU offers an always-free plan alongside premium features for advanced analysis and monitoring.
LightKeeper - Lighthouse testing service with free HAR Matrix view and multi-region testing (3 free regions, 25+ paid), supporting authenticated pages and cross-region performance comparison

Lighthouse Integrations in non-Web Perf services

PageWatch — PageWatch is a tool to find problem pages on your website. It provides insights into spelling errors, layout issues, slow pages (powered by Lighthouse) and more. PageWatch is offered via free and paid plans.
Fluxguard - Fluxguard provides website DOM change monitoring orchestrated with Google Puppeteer, and audited by Lighthouse. Fluxguard is a freemium product, with monthly monitoring of up to 75 pages for free.
Microlink — Microlink is a cloud browser as API. It offers Lighthouse reports on demand, making it easy to build any service on top. Similar functionality is available via the underlying open-source project named browserless.
Wattspeed — Wattspeed is a free tool that generates snapshots - historical captures of your web pages that include Lighthouse scores, a list of technologies, W3C HTML validator results, DOM size, mixed content info, and more.

Plugins

lighthouse-plugin-field-performance - a plugin that adds real-user performance metrics for the URL using the data from Chrome UX Report.
lighthouse-plugin-publisher-ads - a tool to improve ad speed and overall quality through a series of automated audits. At the moment, this is primarily targeted at sites using Google Ad Manager. This tool will aid in resolving discovered problems, providing a tool to be used to evaluate effectiveness of iterative changes while suggesting actionable feedback.
lighthouse-plugin-crux - a plugin that quickly gathers real-user-metrics data from the Chrome UX Report API.

Other awesome open source projects that use Lighthouse.

auto-lighthouse - a CLI for crawling a domain and generating mobile and desktop reports for each page.
Exthouse - Analyze the impact of a browser extension on web performance.
Gimbal - An open source (MIT licensed) tool used to measure, analyze, and budget aspects of a web application. Gimbal also integrates reports with GitHub pull requests.
Gradle Lighthouse Plugin - An open source Gradle plugin that runs Lighthouse tests on multiple URLs and asserts category score thresholds (useful in continuous integration).
lighthouse-badges - Generate gh-badges (shields.io) based on Lighthouse performance.
lighthouse-batch - Run Lighthouse over a number of sites and generate a summary of their metrics/scores.
lighthouse-batch-parallel - Run multiple Lighthouse runs in parallel to accelerate the data collecting process, get the result stream (csv, json, js object) in your own process (warning: performance results may be volatile).
lighthouse-check-action - A GitHub Action to run Lighthouse in a workflow, featuring Slack notifications and report upload to S3.
lighthouse-check-orb - A CircleCI Orb to run Lighthouse in a workflow, featuring Slack notifications and report upload to S3.
andreasonny83/lighthouse-ci - Run Lighthouse and assert scores satisfy your custom thresholds.
GoogleChrome/lighthouse-ci - (official) Automate running Lighthouse for every commit, viewing the changes, and preventing regressions.
lighthouse-ci-action - A GitHub Action that makes it easy to run Lighthouse in CI and keep your pages small using performance budgets.
lighthouse-gh-reporter - Run Lighthouse in CI and report back in a comment on your pull requests
lighthouse-jest-example - Gather performance metrics via Lighthouse and assert results with Jest; uses Puppeteer to start Chrome with network emulation settings defined by WebPageTest.
lighthouse-lambda - Run Lighthouse on AWS Lambda with prebuilt stable desktop Headless Chrome.
lighthouse-matchers - Provides RSpec matchers for executing and evaluating Google Chrome Lighthouse audit scores.
lighthouse-mocha-example - Run Lighthouse performance tests with Mocha and chrome-launcher.
lighthouse-monitor - Run Lighthouse against all your URLs. Send metrics to any backend you want, save all reports with automatic data retention, and compare any two results in a web UI.
lighthouse-persist - Run Lighthouse and upload HTML reports to an AWS S3 bucket.
lighthouse-viewer - Render the Lighthouse JSON into a report, using the Lighthouse Report Renderer repackaged as UMD and ESM. Also available with React, Svelte and Vue wrappers.
lighthouse4u - LH4U provides Google Lighthouse as a service, surfaced by both a friendly UI+API, and backed by Elastic Search for easy querying and visualization.
react-lighthouse-viewer - Render a Lighthouse JSON report in a React Component.
site-audit-seo - CLI tool for SEO site audit, crawl site, lighthouse each page. Output to console and tables in csv, xlsx, json, web or Google Drive.
webpack-lighthouse-plugin - Run Lighthouse from a Webpack build.
cypress-audit - Run Lighthouse and Pa11y audits directly in your E2E test suites.
laravel-lighthouse - Google Lighthouse wrapper for laravel framework to run Google Lighthouse CLI with custom option and can automatically save result in your server directory.
Neodymium - The Neodymium test automation framework integrates Lighthouse for accessibility and Web Vitals verification, allowing programmatic validation and assertion of all audit values.

FAQ

How does Lighthouse work?

See Lighthouse Architecture.

Why is the performance score so low? It looks fine to me.

Lighthouse reports the performance metrics as they would be experienced by a typical mobile user on a 4G connection and a mid-tier ~$200 phone. Even if it loads quickly on your device and network, users in other environments will experience the site very differently.

Why does the performance score change so much?

Lighthouse performance scores will change due to inherent variability in web and network technologies, even if there hasn't been a code change. Test in consistent environments, run Lighthouse multiple times, and beware of variability before drawing conclusions about a performance-impacting change.

Read more in our guide to reducing variability.

Can I configure the lighthouse run?

Yes! Details in Lighthouse configuration.

How does Lighthouse use network throttling, and how can I make it better?

Good question. Network and CPU throttling are applied by default in a Lighthouse run. The network
attempts to emulate slow 4G connectivity and the CPU is slowed down 4x from your machine's default speed. If you
prefer to run Lighthouse without throttling, you'll have to use the CLI and disable it with the
--throttling.* flags mentioned above.

Read more in our guide to network throttling.

Are results sent to a remote server?

Nope. 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.

How do I get localized Lighthouse results via the CLI?

Starting in Lighthouse 8.0, Lighthouse relies entirely on native Intl support and no longer uses an Intl polyfill. If you're using Node 14 or later, there should be no issue because Node is now built with full-icu by default.

However, if you're using a small-icu Node build, you may see Lighthouse log messages about your locale not being available. To remedy this, you can manually install ICU data by using the full-icu module and the --icu-data-dir node flag at launch.

How do I author custom audits to extend Lighthouse?

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.

How do I contribute?

We'd love help writing audits, fixing bugs, and making the tool more useful!
See Contributing to get started.

File: Readme.md

Lighthouse [](https://github.com/GoogleChrome/lighthouse/actions/workflows/ci.yml) [](https://github.com/GoogleChrome/lighthouse/actions/workflows/unit.yml) [](https://github.com/GoogleChrome/lighthouse/actions/workflows/smoke.yml) [](https://codecov.io/gh/GoogleChrome/lighthouse) [](https://lh-build-tracker.herokuapp.com/) [](https://npmjs.org/package/lighthouse)

Lighthouse analyzes web apps and web pages, collecting modern performance metrics and insights on developer best practices.

Using Lighthouse
Associated Products and Projects
FAQ

Using Lighthouse in Chrome DevTools

Lighthouse is integrated directly into the Chrome DevTools, under the "Lighthouse" panel.

Installation: install Chrome.

Run it: open Chrome DevTools, select the Lighthouse panel, and hit "Generate report".

Using the Chrome extension

The Chrome extension was available prior to Lighthouse being available in Chrome Developer Tools, and offers similar functionality.

Installation: install the extension from the Chrome Web Store.

Run it: follow the extension quick-start guide.

Using the Node CLI

[!NOTE]
Lighthouse requires Node 22 (LTS) or later.

Installation:

npm install 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.

CLI options

text

/* Detailed source-code truncated for AI context efficiency. */

Output Examples

lighthouse
# saves `./<HOST>_<DATE>.report.html`

lighthouse --output json
# json output sent to stdout

lighthouse --output html --output-path ./report.html
# saves `./report.html`

# NOTE: specifying an output path with multiple formats ignores your specified extension for *ALL* formats
lighthouse --output json --output html --output-path ./myfile.json
# saves `./myfile.report.json` and `./myfile.report.html`

lighthouse --output json --output html
# saves `./<HOST>_<DATE>.report.json` and `./<HOST>_<DATE>.report.html`

lighthouse --output-path=~/mydir/foo.out --save-assets
# saves `~/mydir/foo.report.html`
# saves `~/mydir/foo-0.trace.json` and `~/mydir/foo-0.devtoolslog.json`

lighthouse --output-path=./report.json --output json
# saves `./report.json`

Lifecycle Examples

You can run a subset of Lighthouse's lifecycle if desired via the --gather-mode (-G) and --audit-mode (-A) CLI flags.

lighthouse http://example.com -G
# launches browser, collects artifacts, saves them to disk (in `./latest-run/`) and quits

lighthouse http://example.com -A
# skips browser interaction, loads artifacts from disk (in `./latest-run/`), runs audits on them, generates report

lighthouse http://example.com -GA
# Normal gather + audit run, but also saves collected artifacts to disk for subsequent -A runs.


# You can optionally provide a custom folder destination to -G/-A/-GA. Without a value, the default will be `$PWD/latest-run`.
lighthouse -GA=./gmailartifacts https://gmail.com

Notes on Error Reporting

Using the Node module

You can also use Lighthouse programmatically with the Node module.

Read Using Lighthouse programmatically for help getting started.
Read Lighthouse Configuration to learn more about the configuration options available.

Viewing a report

Lighthouse can produce a report as JSON or HTML.

HTML report:

Online 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.

Docs & Recipes

Useful documentation, examples, and recipes to get you started.

Docs

Recipes

Plugin - example Lighthouse plugin
Custom Audit example - extend Lighthouse, run your own audits

Videos

The session from Google I/O 2018 covers the new performance engine, upcoming Lighthouse REST API, and using the Chrome UX report to evaluate real-user data.

The session from Google I/O 2017 covers architecture, writing custom audits,
GitHub/Travis/CI integration, headless Chrome, and more:

Click the image to watch the video on YouTube.

Develop

Read on for the basics of hacking on Lighthouse. Also, see Contributing
for detailed information.

Setup

# yarn should be installed first

git clone https://github.com/GoogleChrome/lighthouse

cd lighthouse
yarn
yarn build-all

Run

node cli http://example.com
# append --chrome-flags="--no-sandbox --headless --disable-gpu" if you run into problems connecting to Chrome

Getting started tip: node --inspect-brk cli http://example.com to open up Chrome DevTools and step
through the entire app. See Debugging Node.js with Chrome
DevTools
for more info.

Tests

# lint and test all files
yarn test

# run all unit tests
yarn unit

# run a given unit test (e.g. core/test/audits/byte-efficiency/uses-long-cache-ttl-test.js)
yarn mocha uses-long-cache-ttl

# 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 tsc compiler
yarn type-check

Docs

Some of our docs have tests that run only in CI by default. To modify our documentation, you'll need to run yarn build-pack && yarn test-docs locally to make sure they pass.

Additional Dependencies

brew install jq

Lighthouse Integrations in Web Perf services

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.
HTTPArchive - HTTPArchive tracks how the web is built by crawling 500k pages with Web Page Test, including Lighthouse results, and stores the information in BigQuery where it is publicly available.
Calibre - Calibre is a comprehensive performance monitoring platform running on Lighthouse. See the performance impact of your work before it hits production with GitHub Pull Request Reviews. Track the impact of Third Party scripts. Automate your performance system with a developer-first Node.js API. Try Calibre with a free 15-day trial.
DebugBear - DebugBear is a website monitoring tool based on Lighthouse. See how your scores and metrics changed over time, with a focus on understanding what caused each change. DebugBear is a paid product with a free 30-day trial.
Treo - Treo is Lighthouse as a Service. It provides regression testing, geographical regions, custom networks, and integrations with GitHub & Slack. Treo is a paid product with plans for solo-developers and teams.
PageVitals - PageVitals combines Lighthouse, CrUX and field testing to monitor the performance of websites. See how your website performs over time and get alerted if it gets too slow. Drill down and find the real cause of any performance issue. PageVitals is a paid product with a free 14-day trial.
Screpy - Screpy is a web analysis tool that can analyze all pages of your websites in one dashboard and monitor them with your team. It's powered by Lighthouse and it also includes some different analysis tools (SERP, W3C, Uptime, etc). Screpy has free and paid plans.
Siteimprove Performance — Siteimprove Performance is a web Performance monitoring solution that enables a marketer, manager or decision maker to understand and optimize website load times. Get easy-to-use insights with a focus on quick and impactful wins. Siteimprove Performance is a paid product with a free 14-day trial.
SpeedCurve — SpeedCurve is a tool for continuously monitoring web performance across different browsers, devices, and regions. It can aggregate any metric including Lighthouse scores across multiple pages and sites, and allows you to set performance budgets with Slack or email alerts. SpeedCurve is a paid product with a free 30-day trial.
Foo - Lighthouse-as-a-service offering free and premium plans. Provides monitoring and historical reporting of Lighthouse audits with CircleCI, GitHub, and other integrations. Features include Slack notifications, PR comment reporting and more.
Apdex - Apdex is a website performance service. The main features are historical Lighthouse report visualizations, mobile/desktop options, alerts, uptime monitoring, and more. There are flexible paid plans and a 30-day free trial.
Websu - Websu is an open source project to provide Lighthouse-as-a-Service through a simple HTTP REST API. The main features are ability to host and deploy in your own environment and historical Lighthouse report summaries.
DTEKT.IO - DTEKT is a website performance and uptime monitoring service. It uses lighthouse to provide visibility into the performance of websites from multiple locations on multiple devices. It offers three months free trial and paid plans.
SpeedVitals - SpeedVitals is a Lighthouse powered tool to measure web performance across multiple devices and locations. It has various features like Layout Shift Visualization, Waterfall Chart, Field Data and Resource Graphs. SpeedVitals offers both free and paid plans.
Lighthouse Metrics - Lighthouse Metrics gives you global performance insights with a single test. You can also monitor your websites on a daily or hourly base. Lighthouse Metrics offers free global one-time tests and performance monitoring as a paid feature with a free 14-day trial.
Auditzy - Auditzy™ is a robust website auditing & monitoring tool which lets you analyze your web page(s) pre-user journey. Analyze the Competitor Health Metric, Core Web Vitals, and Technology. Compare your web pages with your competitors to understand where you are leading or lagging. Real-time notification with Slack. Have Seamless Collaboration with Multiple Teams. Automate your Audits hourly, daily, weekly, and so on. It has a free trial with pay as you go plans.
Lighthouse Metrics China - The first Lighthouse metrics tool specifically designed for China. Experience unparalleled website monitoring capabilities with Lighthouse. Gain insights into the fluctuations of your scores and metrics within the realm of the Great Firewall of China, enabling a comprehensive understanding of the factors influencing each change. Lighthouse Metrics China offers both free and paid plans.
DeploymentHawk - DeploymentHawk is an automated site auditing tool powered by Lighthouse. Effortlessly catch performance, accessibility, and SEO issues before they impact your users. DeploymentHawk is a paid product with a free 7-day trial.
Guardius - Guardius is a DevOps and DevSecOps SaaS platform that integrates Lighthouse to deliver automated web performance analysis. It not only provides metrics evaluation and automatic scanning but also enables performance comparisons across different periods and ongoing observation over time. Additionally, Guardius offers predefined and customized alerts tailored to your specific requirements. A free version of Guardius is available for users to explore its features.
Sonā - Powered by Lighthouse amongst others, Sonā delivers in-depth insights into your website’s health. Track changes over time, share reports, and receive actionable recommendations to improve performance, accessibility, SEO, best practices, and security. Sonā is free during its beta period.
FERU - Run Google Lighthouse speed tests from multiple regions worldwide. Lighthouse scores, Core Web Vitals, and mobile performance metrics to easily test your site's speed, accessibility, and SEO. FERU offers an always-free plan alongside premium features for advanced analysis and monitoring.
LightKeeper - Lighthouse testing service with free HAR Matrix view and multi-region testing (3 free regions, 25+ paid), supporting authenticated pages and cross-region performance comparison

Lighthouse Integrations in non-Web Perf services

PageWatch — PageWatch is a tool to find problem pages on your website. It provides insights into spelling errors, layout issues, slow pages (powered by Lighthouse) and more. PageWatch is offered via free and paid plans.
Fluxguard - Fluxguard provides website DOM change monitoring orchestrated with Google Puppeteer, and audited by Lighthouse. Fluxguard is a freemium product, with monthly monitoring of up to 75 pages for free.
Microlink — Microlink is a cloud browser as API. It offers Lighthouse reports on demand, making it easy to build any service on top. Similar functionality is available via the underlying open-source project named browserless.
Wattspeed — Wattspeed is a free tool that generates snapshots - historical captures of your web pages that include Lighthouse scores, a list of technologies, W3C HTML validator results, DOM size, mixed content info, and more.

Plugins

lighthouse-plugin-field-performance - a plugin that adds real-user performance metrics for the URL using the data from Chrome UX Report.
lighthouse-plugin-publisher-ads - a tool to improve ad speed and overall quality through a series of automated audits. At the moment, this is primarily targeted at sites using Google Ad Manager. This tool will aid in resolving discovered problems, providing a tool to be used to evaluate effectiveness of iterative changes while suggesting actionable feedback.
lighthouse-plugin-crux - a plugin that quickly gathers real-user-metrics data from the Chrome UX Report API.

Other awesome open source projects that use Lighthouse.

auto-lighthouse - a CLI for crawling a domain and generating mobile and desktop reports for each page.
Exthouse - Analyze the impact of a browser extension on web performance.
Gimbal - An open source (MIT licensed) tool used to measure, analyze, and budget aspects of a web application. Gimbal also integrates reports with GitHub pull requests.
Gradle Lighthouse Plugin - An open source Gradle plugin that runs Lighthouse tests on multiple URLs and asserts category score thresholds (useful in continuous integration).
lighthouse-badges - Generate gh-badges (shields.io) based on Lighthouse performance.
lighthouse-batch - Run Lighthouse over a number of sites and generate a summary of their metrics/scores.
lighthouse-batch-parallel - Run multiple Lighthouse runs in parallel to accelerate the data collecting process, get the result stream (csv, json, js object) in your own process (warning: performance results may be volatile).
lighthouse-check-action - A GitHub Action to run Lighthouse in a workflow, featuring Slack notifications and report upload to S3.
lighthouse-check-orb - A CircleCI Orb to run Lighthouse in a workflow, featuring Slack notifications and report upload to S3.
andreasonny83/lighthouse-ci - Run Lighthouse and assert scores satisfy your custom thresholds.
GoogleChrome/lighthouse-ci - (official) Automate running Lighthouse for every commit, viewing the changes, and preventing regressions.
lighthouse-ci-action - A GitHub Action that makes it easy to run Lighthouse in CI and keep your pages small using performance budgets.
lighthouse-gh-reporter - Run Lighthouse in CI and report back in a comment on your pull requests
lighthouse-jest-example - Gather performance metrics via Lighthouse and assert results with Jest; uses Puppeteer to start Chrome with network emulation settings defined by WebPageTest.
lighthouse-lambda - Run Lighthouse on AWS Lambda with prebuilt stable desktop Headless Chrome.
lighthouse-matchers - Provides RSpec matchers for executing and evaluating Google Chrome Lighthouse audit scores.
lighthouse-mocha-example - Run Lighthouse performance tests with Mocha and chrome-launcher.
lighthouse-monitor - Run Lighthouse against all your URLs. Send metrics to any backend you want, save all reports with automatic data retention, and compare any two results in a web UI.
lighthouse-persist - Run Lighthouse and upload HTML reports to an AWS S3 bucket.
lighthouse-viewer - Render the Lighthouse JSON into a report, using the Lighthouse Report Renderer repackaged as UMD and ESM. Also available with React, Svelte and Vue wrappers.
lighthouse4u - LH4U provides Google Lighthouse as a service, surfaced by both a friendly UI+API, and backed by Elastic Search for easy querying and visualization.
react-lighthouse-viewer - Render a Lighthouse JSON report in a React Component.
site-audit-seo - CLI tool for SEO site audit, crawl site, lighthouse each page. Output to console and tables in csv, xlsx, json, web or Google Drive.
webpack-lighthouse-plugin - Run Lighthouse from a Webpack build.
cypress-audit - Run Lighthouse and Pa11y audits directly in your E2E test suites.
laravel-lighthouse - Google Lighthouse wrapper for laravel framework to run Google Lighthouse CLI with custom option and can automatically save result in your server directory.
Neodymium - The Neodymium test automation framework integrates Lighthouse for accessibility and Web Vitals verification, allowing programmatic validation and assertion of all audit values.

FAQ

How does Lighthouse work?

See Lighthouse Architecture.

Why is the performance score so low? It looks fine to me.

Are results sent to a remote server?

Nope. 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.

How do I get localized Lighthouse results via the CLI?

How do I author custom audits to extend Lighthouse?

Tip: see Lighthouse Architecture for more information
on terminology and architecture.

If you're interested in running your own custom audits, check out our
Custom Audit Example over in recipes.

How do I contribute?

We'd love help writing audits, fixing bugs, and making the tool more useful!
See Contributing to get started.

File: readme.md

Lighthouse [](https://github.com/GoogleChrome/lighthouse/actions/workflows/ci.yml) [](https://github.com/GoogleChrome/lighthouse/actions/workflows/unit.yml) [](https://github.com/GoogleChrome/lighthouse/actions/workflows/smoke.yml) [](https://codecov.io/gh/GoogleChrome/lighthouse) [](https://lh-build-tracker.herokuapp.com/) [](https://npmjs.org/package/lighthouse)

Lighthouse analyzes web apps and web pages, collecting modern performance metrics and insights on developer best practices.

Using Lighthouse
Associated Products and Projects
FAQ

Using Lighthouse in Chrome DevTools

Lighthouse is integrated directly into the Chrome DevTools, under the "Lighthouse" panel.

Installation: install Chrome.

Run it: open Chrome DevTools, select the Lighthouse panel, and hit "Generate report".

Using the Chrome extension

The Chrome extension was available prior to Lighthouse being available in Chrome Developer Tools, and offers similar functionality.

Installation: install the extension from the Chrome Web Store.

Run it: follow the extension quick-start guide.

Using the Node CLI

[!NOTE]
Lighthouse requires Node 22 (LTS) or later.

Installation:

npm install 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.

CLI options

text

/* Detailed source-code truncated for AI context efficiency. */

Output Examples

lighthouse
# saves `./<HOST>_<DATE>.report.html`

lighthouse --output json
# json output sent to stdout

lighthouse --output html --output-path ./report.html
# saves `./report.html`

# NOTE: specifying an output path with multiple formats ignores your specified extension for *ALL* formats
lighthouse --output json --output html --output-path ./myfile.json
# saves `./myfile.report.json` and `./myfile.report.html`

lighthouse --output json --output html
# saves `./<HOST>_<DATE>.report.json` and `./<HOST>_<DATE>.report.html`

lighthouse --output-path=~/mydir/foo.out --save-assets
# saves `~/mydir/foo.report.html`
# saves `~/mydir/foo-0.trace.json` and `~/mydir/foo-0.devtoolslog.json`

lighthouse --output-path=./report.json --output json
# saves `./report.json`

Lifecycle Examples

You can run a subset of Lighthouse's lifecycle if desired via the --gather-mode (-G) and --audit-mode (-A) CLI flags.

lighthouse http://example.com -G
# launches browser, collects artifacts, saves them to disk (in `./latest-run/`) and quits

lighthouse http://example.com -A
# skips browser interaction, loads artifacts from disk (in `./latest-run/`), runs audits on them, generates report

lighthouse http://example.com -GA
# Normal gather + audit run, but also saves collected artifacts to disk for subsequent -A runs.


# You can optionally provide a custom folder destination to -G/-A/-GA. Without a value, the default will be `$PWD/latest-run`.
lighthouse -GA=./gmailartifacts https://gmail.com

Notes on Error Reporting

Using the Node module

You can also use Lighthouse programmatically with the Node module.

Read Using Lighthouse programmatically for help getting started.
Read Lighthouse Configuration to learn more about the configuration options available.

Viewing a report

Lighthouse can produce a report as JSON or HTML.

HTML report:

Online 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.

Docs & Recipes

Useful documentation, examples, and recipes to get you started.

Docs

Recipes

Plugin - example Lighthouse plugin
Custom Audit example - extend Lighthouse, run your own audits

Videos

The session from Google I/O 2018 covers the new performance engine, upcoming Lighthouse REST API, and using the Chrome UX report to evaluate real-user data.

The session from Google I/O 2017 covers architecture, writing custom audits,
GitHub/Travis/CI integration, headless Chrome, and more:

Click the image to watch the video on YouTube.

Develop

Read on for the basics of hacking on Lighthouse. Also, see Contributing
for detailed information.

Setup

# yarn should be installed first

git clone https://github.com/GoogleChrome/lighthouse

cd lighthouse
yarn
yarn build-all

Run

node cli http://example.com
# append --chrome-flags="--no-sandbox --headless --disable-gpu" if you run into problems connecting to Chrome

Getting started tip: node --inspect-brk cli http://example.com to open up Chrome DevTools and step
through the entire app. See Debugging Node.js with Chrome
DevTools
for more info.

Tests

# lint and test all files
yarn test

# run all unit tests
yarn unit

# run a given unit test (e.g. core/test/audits/byte-efficiency/uses-long-cache-ttl-test.js)
yarn mocha uses-long-cache-ttl

# 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 tsc compiler
yarn type-check

Docs

Some of our docs have tests that run only in CI by default. To modify our documentation, you'll need to run yarn build-pack && yarn test-docs locally to make sure they pass.

Additional Dependencies

brew install jq

Lighthouse Integrations in Web Perf services

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.
HTTPArchive - HTTPArchive tracks how the web is built by crawling 500k pages with Web Page Test, including Lighthouse results, and stores the information in BigQuery where it is publicly available.
Calibre - Calibre is a comprehensive performance monitoring platform running on Lighthouse. See the performance impact of your work before it hits production with GitHub Pull Request Reviews. Track the impact of Third Party scripts. Automate your performance system with a developer-first Node.js API. Try Calibre with a free 15-day trial.
DebugBear - DebugBear is a website monitoring tool based on Lighthouse. See how your scores and metrics changed over time, with a focus on understanding what caused each change. DebugBear is a paid product with a free 30-day trial.
Treo - Treo is Lighthouse as a Service. It provides regression testing, geographical regions, custom networks, and integrations with GitHub & Slack. Treo is a paid product with plans for solo-developers and teams.
PageVitals - PageVitals combines Lighthouse, CrUX and field testing to monitor the performance of websites. See how your website performs over time and get alerted if it gets too slow. Drill down and find the real cause of any performance issue. PageVitals is a paid product with a free 14-day trial.
Screpy - Screpy is a web analysis tool that can analyze all pages of your websites in one dashboard and monitor them with your team. It's powered by Lighthouse and it also includes some different analysis tools (SERP, W3C, Uptime, etc). Screpy has free and paid plans.
Siteimprove Performance — Siteimprove Performance is a web Performance monitoring solution that enables a marketer, manager or decision maker to understand and optimize website load times. Get easy-to-use insights with a focus on quick and impactful wins. Siteimprove Performance is a paid product with a free 14-day trial.
SpeedCurve — SpeedCurve is a tool for continuously monitoring web performance across different browsers, devices, and regions. It can aggregate any metric including Lighthouse scores across multiple pages and sites, and allows you to set performance budgets with Slack or email alerts. SpeedCurve is a paid product with a free 30-day trial.
Foo - Lighthouse-as-a-service offering free and premium plans. Provides monitoring and historical reporting of Lighthouse audits with CircleCI, GitHub, and other integrations. Features include Slack notifications, PR comment reporting and more.
Apdex - Apdex is a website performance service. The main features are historical Lighthouse report visualizations, mobile/desktop options, alerts, uptime monitoring, and more. There are flexible paid plans and a 30-day free trial.
Websu - Websu is an open source project to provide Lighthouse-as-a-Service through a simple HTTP REST API. The main features are ability to host and deploy in your own environment and historical Lighthouse report summaries.
DTEKT.IO - DTEKT is a website performance and uptime monitoring service. It uses lighthouse to provide visibility into the performance of websites from multiple locations on multiple devices. It offers three months free trial and paid plans.
SpeedVitals - SpeedVitals is a Lighthouse powered tool to measure web performance across multiple devices and locations. It has various features like Layout Shift Visualization, Waterfall Chart, Field Data and Resource Graphs. SpeedVitals offers both free and paid plans.
Lighthouse Metrics - Lighthouse Metrics gives you global performance insights with a single test. You can also monitor your websites on a daily or hourly base. Lighthouse Metrics offers free global one-time tests and performance monitoring as a paid feature with a free 14-day trial.
Auditzy - Auditzy™ is a robust website auditing & monitoring tool which lets you analyze your web page(s) pre-user journey. Analyze the Competitor Health Metric, Core Web Vitals, and Technology. Compare your web pages with your competitors to understand where you are leading or lagging. Real-time notification with Slack. Have Seamless Collaboration with Multiple Teams. Automate your Audits hourly, daily, weekly, and so on. It has a free trial with pay as you go plans.
Lighthouse Metrics China - The first Lighthouse metrics tool specifically designed for China. Experience unparalleled website monitoring capabilities with Lighthouse. Gain insights into the fluctuations of your scores and metrics within the realm of the Great Firewall of China, enabling a comprehensive understanding of the factors influencing each change. Lighthouse Metrics China offers both free and paid plans.
DeploymentHawk - DeploymentHawk is an automated site auditing tool powered by Lighthouse. Effortlessly catch performance, accessibility, and SEO issues before they impact your users. DeploymentHawk is a paid product with a free 7-day trial.
Guardius - Guardius is a DevOps and DevSecOps SaaS platform that integrates Lighthouse to deliver automated web performance analysis. It not only provides metrics evaluation and automatic scanning but also enables performance comparisons across different periods and ongoing observation over time. Additionally, Guardius offers predefined and customized alerts tailored to your specific requirements. A free version of Guardius is available for users to explore its features.
Sonā - Powered by Lighthouse amongst others, Sonā delivers in-depth insights into your website’s health. Track changes over time, share reports, and receive actionable recommendations to improve performance, accessibility, SEO, best practices, and security. Sonā is free during its beta period.
FERU - Run Google Lighthouse speed tests from multiple regions worldwide. Lighthouse scores, Core Web Vitals, and mobile performance metrics to easily test your site's speed, accessibility, and SEO. FERU offers an always-free plan alongside premium features for advanced analysis and monitoring.
LightKeeper - Lighthouse testing service with free HAR Matrix view and multi-region testing (3 free regions, 25+ paid), supporting authenticated pages and cross-region performance comparison

Lighthouse Integrations in non-Web Perf services

PageWatch — PageWatch is a tool to find problem pages on your website. It provides insights into spelling errors, layout issues, slow pages (powered by Lighthouse) and more. PageWatch is offered via free and paid plans.
Fluxguard - Fluxguard provides website DOM change monitoring orchestrated with Google Puppeteer, and audited by Lighthouse. Fluxguard is a freemium product, with monthly monitoring of up to 75 pages for free.
Microlink — Microlink is a cloud browser as API. It offers Lighthouse reports on demand, making it easy to build any service on top. Similar functionality is available via the underlying open-source project named browserless.
Wattspeed — Wattspeed is a free tool that generates snapshots - historical captures of your web pages that include Lighthouse scores, a list of technologies, W3C HTML validator results, DOM size, mixed content info, and more.

Plugins

lighthouse-plugin-field-performance - a plugin that adds real-user performance metrics for the URL using the data from Chrome UX Report.
lighthouse-plugin-publisher-ads - a tool to improve ad speed and overall quality through a series of automated audits. At the moment, this is primarily targeted at sites using Google Ad Manager. This tool will aid in resolving discovered problems, providing a tool to be used to evaluate effectiveness of iterative changes while suggesting actionable feedback.
lighthouse-plugin-crux - a plugin that quickly gathers real-user-metrics data from the Chrome UX Report API.

Other awesome open source projects that use Lighthouse.

auto-lighthouse - a CLI for crawling a domain and generating mobile and desktop reports for each page.
Exthouse - Analyze the impact of a browser extension on web performance.
Gimbal - An open source (MIT licensed) tool used to measure, analyze, and budget aspects of a web application. Gimbal also integrates reports with GitHub pull requests.
Gradle Lighthouse Plugin - An open source Gradle plugin that runs Lighthouse tests on multiple URLs and asserts category score thresholds (useful in continuous integration).
lighthouse-badges - Generate gh-badges (shields.io) based on Lighthouse performance.
lighthouse-batch - Run Lighthouse over a number of sites and generate a summary of their metrics/scores.
lighthouse-batch-parallel - Run multiple Lighthouse runs in parallel to accelerate the data collecting process, get the result stream (csv, json, js object) in your own process (warning: performance results may be volatile).
lighthouse-check-action - A GitHub Action to run Lighthouse in a workflow, featuring Slack notifications and report upload to S3.
lighthouse-check-orb - A CircleCI Orb to run Lighthouse in a workflow, featuring Slack notifications and report upload to S3.
andreasonny83/lighthouse-ci - Run Lighthouse and assert scores satisfy your custom thresholds.
GoogleChrome/lighthouse-ci - (official) Automate running Lighthouse for every commit, viewing the changes, and preventing regressions.
lighthouse-ci-action - A GitHub Action that makes it easy to run Lighthouse in CI and keep your pages small using performance budgets.
lighthouse-gh-reporter - Run Lighthouse in CI and report back in a comment on your pull requests
lighthouse-jest-example - Gather performance metrics via Lighthouse and assert results with Jest; uses Puppeteer to start Chrome with network emulation settings defined by WebPageTest.
lighthouse-lambda - Run Lighthouse on AWS Lambda with prebuilt stable desktop Headless Chrome.
lighthouse-matchers - Provides RSpec matchers for executing and evaluating Google Chrome Lighthouse audit scores.
lighthouse-mocha-example - Run Lighthouse performance tests with Mocha and chrome-launcher.
lighthouse-monitor - Run Lighthouse against all your URLs. Send metrics to any backend you want, save all reports with automatic data retention, and compare any two results in a web UI.
lighthouse-persist - Run Lighthouse and upload HTML reports to an AWS S3 bucket.
lighthouse-viewer - Render the Lighthouse JSON into a report, using the Lighthouse Report Renderer repackaged as UMD and ESM. Also available with React, Svelte and Vue wrappers.
lighthouse4u - LH4U provides Google Lighthouse as a service, surfaced by both a friendly UI+API, and backed by Elastic Search for easy querying and visualization.
react-lighthouse-viewer - Render a Lighthouse JSON report in a React Component.
site-audit-seo - CLI tool for SEO site audit, crawl site, lighthouse each page. Output to console and tables in csv, xlsx, json, web or Google Drive.
webpack-lighthouse-plugin - Run Lighthouse from a Webpack build.
cypress-audit - Run Lighthouse and Pa11y audits directly in your E2E test suites.
laravel-lighthouse - Google Lighthouse wrapper for laravel framework to run Google Lighthouse CLI with custom option and can automatically save result in your server directory.
Neodymium - The Neodymium test automation framework integrates Lighthouse for accessibility and Web Vitals verification, allowing programmatic validation and assertion of all audit values.

FAQ

How does Lighthouse work?

See Lighthouse Architecture.

Why is the performance score so low? It looks fine to me.

Why does the performance score change so much?

Read more in our guide to reducing variability.

Can I configure the lighthouse run?

Yes! Details in Lighthouse configuration.

How does Lighthouse use network throttling, and how can I make it better?

Read more in our guide to network throttling.

Are results sent to a remote server?

Nope. 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.

How do I get localized Lighthouse results via the CLI?

How do I author custom audits to extend Lighthouse?

Tip: see Lighthouse Architecture for more information
on terminology and architecture.

If you're interested in running your own custom audits, check out our
Custom Audit Example over in recipes.

How do I contribute?

We'd love help writing audits, fixing bugs, and making the tool more useful!
See Contributing to get started.

File: docs/README.md

This directory contains useful documentation, examples (keep reading),
and recipes to get you started. For an overview of Lighthouse's
internals, see Lighthouse Architecture.

Using programmatically

The example below shows how to run Lighthouse programmatically as a Node module. It
assumes you've installed Lighthouse as a dependency (yarn add --dev lighthouse).

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);

// `.report` is the HTML report as a string
const reportHtml = runnerResult.report;
fs.writeFileSync('lhreport.html', reportHtml);

// `.lhr` is the Lighthouse Result as a JS object
console.log('Report is done for', runnerResult.lhr.finalDisplayedUrl);
console.log('Performance score was', runnerResult.lhr.categories.performance.score * 100);

chrome.kill();

Performance-only Lighthouse run

Many modules consuming Lighthouse are only interested in the performance numbers.
You can limit the audits you run to a particular category or set of audits.

const flags = {onlyCategories: ['performance']};
await lighthouse(url, flags);

You can also craft your own config (e.g. experimental-config.js) for custom runs. Also see the basic custom audit recipe.

Differences from CLI flags

Note that some flag functionality is only available to the CLI. The set of shared flags that work in both node and CLI can be found in our typedefs. In most cases, the functionality is not offered in the node module simply because it is easier and more flexible to do it yourself.

CLI Flag	Differences in Node
`port`	Only specifies which port to use, Chrome is not launched for you.
`chromeFlags`	Ignored, Chrome is not launched for you.
`outputPath`	Ignored, output is returned as string in `.report` property.
`saveAssets`	Ignored, artifacts are returned in `.artifacts` property.
`view`	Ignored, use the `open` npm module if you want this functionality.
`enableErrorReporting`	Ignored, error reporting is always disabled for node.
`listAllAudits`	Ignored, not relevant in programmatic use.
`listTraceCategories`	Ignored, not relevant in programmatic use.
`configPath`	Ignored, pass the config in as the 3rd argument to `lighthouse`.
`preset`	Ignored, pass the config in as the 3rd argument to `lighthouse`.
`verbose`	Ignored, use `logLevel` instead.
`quiet`	Ignored, use `logLevel` instead.

Turn on logging

If you want to see log output as Lighthouse runs, set an appropriate logging level in your code and pass
the logLevel flag when calling lighthouse.

javascript

const flags = {logLevel: 'info'};
await lighthouse('https://example.com', flags);

Configuration

In order to extend the Lighthouse configuration programmatically, you need to pass the config object as the 3rd argument. If omitted, a default configuration is used.

Example:

{
  extends: 'lighthouse:default',
  settings: {
    onlyAudits: [
      'speed-index',
      'interactive',
    ],
  },
}

You can extend base configuration from lighthouse:default, or you can build up your own configuration from scratch to have complete control.

For more information on the types of config you can provide, see Lighthouse Configuration.

Testing on a site with authentication

When installed globally via npm i lighthouse or yarn global add lighthouse,
chrome-debug is added to your PATH. This binary launches a standalone Chrome
instance with an open debugging port.

Run chrome-debug. This will log the debugging port of your Chrome instance
Navigate to your site and log in.
In a separate terminal tab, run lighthouse http://mysite.com --port port-number using the port number from chrome-debug.

Testing on a site with an untrusted certificate

When testing a site with an untrusted certificate, Chrome will be unable to load the page and so the Lighthouse report will mostly contain errors.

If this certificate is one you control and is necessary for development (for instance, localhost with a self-signed certificate for local HTTP/2 testing), we recommend you add the certificate to your locally-trusted certificate store. In Chrome, see Settings > Privacy and Security > Manage certificates or consult instructions for adding to the certificate store in your operating system.

Alternatively, you can instruct Chrome to ignore the invalid certificate by adding the Lighthouse CLI flag --chrome-flags="--ignore-certificate-errors". However, you must be as careful with this flag as it's equivalent to browsing the web with TLS disabled. Any content loaded by the test page (e.g. third-party scripts or iframed ads) will also not be subject to certificate checks, opening up avenues for MitM attacks. For these reasons, we recommend the earlier solution of adding the certificate to your local cert store.

Testing on a mobile device

Lighthouse can run against a real mobile device. You can follow the Remote Debugging on Android (Legacy Workflow) up through step 3.3, but the TL;DR is install & run adb, enable USB debugging, then port forward 9222 from the device to the machine with Lighthouse.

You'll likely want to use the CLI flags --screenEmulation.disabled --throttling.cpuSlowdownMultiplier=1 --throttling-method=provided to disable any additional emulation.

$ adb kill-server

$ adb devices -l
* daemon not running. starting it now on port 5037 *
* daemon started successfully *
00a2fd8b1e631fcb       device usb:335682009X product:bullhead model:Nexus_5X device:bullhead

$ adb forward tcp:9222 localabstract:chrome_devtools_remote

$ lighthouse --port=9222 --screenEmulation.disabled --throttling.cpuSlowdownMultiplier=1 --throttling-method=provided https://example.com

Lighthouse as trace processor

Lighthouse can be used to analyze trace and performance data collected from other tools (like WebPageTest and ChromeDriver). The Trace and DevtoolsLog artifact items can be provided using a string for the absolute path on disk if they're saved with .trace.json and .devtoolslog.json file extensions, respectively. The DevtoolsLog array is captured from the Network and Page domains (a la ChromeDriver's enableNetwork and enablePage options).

As an example, here's a trace-only run that reports on user timings and critical request chains:

`config.json`

json

{
  "settings": {
    "auditMode": "/User/me/lighthouse/core/test/fixtures/artifacts/perflog/",
  },
  "audits": [
    "user-timings",
    "critical-request-chains"
  ],
  "categories": {
    "performance": {
      "name": "Performance Metrics",
      "description": "These encapsulate your web app's performance.",
      "audits": [
        {"id": "user-timings", "weight": 1},
        {"id": "critical-request-chains", "weight": 1}
      ]
    }
  }
}

Then, run with: lighthouse --config-path=config.json http://www.random.url

File: docs/Readme.md

This directory contains useful documentation, examples (keep reading),
and recipes to get you started. For an overview of Lighthouse's
internals, see Lighthouse Architecture.

Using programmatically

The example below shows how to run Lighthouse programmatically as a Node module. It
assumes you've installed Lighthouse as a dependency (yarn add --dev lighthouse).

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);

// `.report` is the HTML report as a string
const reportHtml = runnerResult.report;
fs.writeFileSync('lhreport.html', reportHtml);

// `.lhr` is the Lighthouse Result as a JS object
console.log('Report is done for', runnerResult.lhr.finalDisplayedUrl);
console.log('Performance score was', runnerResult.lhr.categories.performance.score * 100);

chrome.kill();

Performance-only Lighthouse run

Many modules consuming Lighthouse are only interested in the performance numbers.
You can limit the audits you run to a particular category or set of audits.

const flags = {onlyCategories: ['performance']};
await lighthouse(url, flags);

You can also craft your own config (e.g. experimental-config.js) for custom runs. Also see the basic custom audit recipe.

Differences from CLI flags

CLI Flag	Differences in Node
`port`	Only specifies which port to use, Chrome is not launched for you.
`chromeFlags`	Ignored, Chrome is not launched for you.
`outputPath`	Ignored, output is returned as string in `.report` property.
`saveAssets`	Ignored, artifacts are returned in `.artifacts` property.
`view`	Ignored, use the `open` npm module if you want this functionality.
`enableErrorReporting`	Ignored, error reporting is always disabled for node.
`listAllAudits`	Ignored, not relevant in programmatic use.
`listTraceCategories`	Ignored, not relevant in programmatic use.
`configPath`	Ignored, pass the config in as the 3rd argument to `lighthouse`.
`preset`	Ignored, pass the config in as the 3rd argument to `lighthouse`.
`verbose`	Ignored, use `logLevel` instead.
`quiet`	Ignored, use `logLevel` instead.

Turn on logging

If you want to see log output as Lighthouse runs, set an appropriate logging level in your code and pass
the logLevel flag when calling lighthouse.

javascript

const flags = {logLevel: 'info'};
await lighthouse('https://example.com', flags);

Configuration

In order to extend the Lighthouse configuration programmatically, you need to pass the config object as the 3rd argument. If omitted, a default configuration is used.

Example:

{
  extends: 'lighthouse:default',
  settings: {
    onlyAudits: [
      'speed-index',
      'interactive',
    ],
  },
}

You can extend base configuration from lighthouse:default, or you can build up your own configuration from scratch to have complete control.

For more information on the types of config you can provide, see Lighthouse Configuration.

Testing on a site with authentication

When installed globally via npm i lighthouse or yarn global add lighthouse,
chrome-debug is added to your PATH. This binary launches a standalone Chrome
instance with an open debugging port.

Run chrome-debug. This will log the debugging port of your Chrome instance
Navigate to your site and log in.
In a separate terminal tab, run lighthouse http://mysite.com --port port-number using the port number from chrome-debug.

Testing on a site with an untrusted certificate

When testing a site with an untrusted certificate, Chrome will be unable to load the page and so the Lighthouse report will mostly contain errors.

Testing on a mobile device

You'll likely want to use the CLI flags --screenEmulation.disabled --throttling.cpuSlowdownMultiplier=1 --throttling-method=provided to disable any additional emulation.

$ adb kill-server

$ adb devices -l
* daemon not running. starting it now on port 5037 *
* daemon started successfully *
00a2fd8b1e631fcb       device usb:335682009X product:bullhead model:Nexus_5X device:bullhead

$ adb forward tcp:9222 localabstract:chrome_devtools_remote

$ lighthouse --port=9222 --screenEmulation.disabled --throttling.cpuSlowdownMultiplier=1 --throttling-method=provided https://example.com

Lighthouse as trace processor

As an example, here's a trace-only run that reports on user timings and critical request chains:

`config.json`

json

{
  "settings": {
    "auditMode": "/User/me/lighthouse/core/test/fixtures/artifacts/perflog/",
  },
  "audits": [
    "user-timings",
    "critical-request-chains"
  ],
  "categories": {
    "performance": {
      "name": "Performance Metrics",
      "description": "These encapsulate your web app's performance.",
      "audits": [
        {"id": "user-timings", "weight": 1},
        {"id": "critical-request-chains", "weight": 1}
      ]
    }
  }
}

Then, run with: lighthouse --config-path=config.json http://www.random.url

File: docs/readme.md

This directory contains useful documentation, examples (keep reading),
and recipes to get you started. For an overview of Lighthouse's
internals, see Lighthouse Architecture.

Using programmatically

The example below shows how to run Lighthouse programmatically as a Node module. It
assumes you've installed Lighthouse as a dependency (yarn add --dev lighthouse).

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);

// `.report` is the HTML report as a string
const reportHtml = runnerResult.report;
fs.writeFileSync('lhreport.html', reportHtml);

// `.lhr` is the Lighthouse Result as a JS object
console.log('Report is done for', runnerResult.lhr.finalDisplayedUrl);
console.log('Performance score was', runnerResult.lhr.categories.performance.score * 100);

chrome.kill();

Performance-only Lighthouse run

Many modules consuming Lighthouse are only interested in the performance numbers.
You can limit the audits you run to a particular category or set of audits.

const flags = {onlyCategories: ['performance']};
await lighthouse(url, flags);

You can also craft your own config (e.g. experimental-config.js) for custom runs. Also see the basic custom audit recipe.

Differences from CLI flags

CLI Flag	Differences in Node
`port`	Only specifies which port to use, Chrome is not launched for you.
`chromeFlags`	Ignored, Chrome is not launched for you.
`outputPath`	Ignored, output is returned as string in `.report` property.
`saveAssets`	Ignored, artifacts are returned in `.artifacts` property.
`view`	Ignored, use the `open` npm module if you want this functionality.
`enableErrorReporting`	Ignored, error reporting is always disabled for node.
`listAllAudits`	Ignored, not relevant in programmatic use.
`listTraceCategories`	Ignored, not relevant in programmatic use.
`configPath`	Ignored, pass the config in as the 3rd argument to `lighthouse`.
`preset`	Ignored, pass the config in as the 3rd argument to `lighthouse`.
`verbose`	Ignored, use `logLevel` instead.
`quiet`	Ignored, use `logLevel` instead.

Turn on logging

If you want to see log output as Lighthouse runs, set an appropriate logging level in your code and pass
the logLevel flag when calling lighthouse.

javascript

const flags = {logLevel: 'info'};
await lighthouse('https://example.com', flags);

Configuration

In order to extend the Lighthouse configuration programmatically, you need to pass the config object as the 3rd argument. If omitted, a default configuration is used.

Example:

{
  extends: 'lighthouse:default',
  settings: {
    onlyAudits: [
      'speed-index',
      'interactive',
    ],
  },
}

You can extend base configuration from lighthouse:default, or you can build up your own configuration from scratch to have complete control.

For more information on the types of config you can provide, see Lighthouse Configuration.

Testing on a site with authentication

When installed globally via npm i lighthouse or yarn global add lighthouse,
chrome-debug is added to your PATH. This binary launches a standalone Chrome
instance with an open debugging port.

Run chrome-debug. This will log the debugging port of your Chrome instance
Navigate to your site and log in.
In a separate terminal tab, run lighthouse http://mysite.com --port port-number using the port number from chrome-debug.

Testing on a site with an untrusted certificate

When testing a site with an untrusted certificate, Chrome will be unable to load the page and so the Lighthouse report will mostly contain errors.

Testing on a mobile device

You'll likely want to use the CLI flags --screenEmulation.disabled --throttling.cpuSlowdownMultiplier=1 --throttling-method=provided to disable any additional emulation.

$ adb kill-server

$ adb devices -l
* daemon not running. starting it now on port 5037 *
* daemon started successfully *
00a2fd8b1e631fcb       device usb:335682009X product:bullhead model:Nexus_5X device:bullhead

$ adb forward tcp:9222 localabstract:chrome_devtools_remote

$ lighthouse --port=9222 --screenEmulation.disabled --throttling.cpuSlowdownMultiplier=1 --throttling-method=provided https://example.com

Lighthouse as trace processor

As an example, here's a trace-only run that reports on user timings and critical request chains:

`config.json`

json

{
  "settings": {
    "auditMode": "/User/me/lighthouse/core/test/fixtures/artifacts/perflog/",
  },
  "audits": [
    "user-timings",
    "critical-request-chains"
  ],
  "categories": {
    "performance": {
      "name": "Performance Metrics",
      "description": "These encapsulate your web app's performance.",
      "audits": [
        {"id": "user-timings", "weight": 1},
        {"id": "critical-request-chains", "weight": 1}
      ]
    }
  }
}

Then, run with: lighthouse --config-path=config.json http://www.random.url

File: README.md Copy Chapter

Using Lighthouse in Chrome DevTools Copy Chapter

Using the Chrome extension Copy Chapter

Using the Node CLI Copy Chapter

CLI options Copy Section

Output Examples

Lifecycle Examples

Notes on Error Reporting

Using the Node module Copy Chapter

Viewing a report Copy Chapter

Online Viewer Copy Section

Docs & Recipes Copy Chapter

Develop Copy Chapter

Setup Copy Section

Run Copy Section

Tests Copy Section

Docs Copy Section

Lighthouse Integrations in Web Perf services Copy Chapter

Lighthouse Integrations in non-Web Perf services Copy Chapter

Plugins Copy Chapter

Related projects Copy Chapter

FAQ Copy Chapter

How does Lighthouse work? Copy Section

Why is the performance score so low? It looks fine to me. Copy Section

Why does the performance score change so much? Copy Section

Can I configure the lighthouse run? Copy Section

How does Lighthouse use network throttling, and how can I make it better? Copy Section

Are results sent to a remote server? Copy Section

How do I get localized Lighthouse results via the CLI? Copy Section

How do I author custom audits to extend Lighthouse? Copy Section

How do I contribute? Copy Section

File: Readme.md Copy Chapter

Using Lighthouse in Chrome DevTools Copy Chapter

Using the Chrome extension Copy Chapter

Using the Node CLI Copy Chapter

CLI options Copy Section

Output Examples

Lifecycle Examples

Notes on Error Reporting

Using the Node module Copy Chapter

Viewing a report Copy Chapter

Online Viewer Copy Section

Docs & Recipes Copy Chapter

Develop Copy Chapter

Setup Copy Section

Run Copy Section

Tests Copy Section

Docs Copy Section

Lighthouse Integrations in Web Perf services Copy Chapter

Lighthouse Integrations in non-Web Perf services Copy Chapter

Plugins Copy Chapter

Related projects Copy Chapter

FAQ Copy Chapter

How does Lighthouse work? Copy Section

Why is the performance score so low? It looks fine to me. Copy Section

Why does the performance score change so much? Copy Section

Can I configure the lighthouse run? Copy Section

How does Lighthouse use network throttling, and how can I make it better? Copy Section

Are results sent to a remote server? Copy Section

How do I get localized Lighthouse results via the CLI? Copy Section

How do I author custom audits to extend Lighthouse? Copy Section

How do I contribute? Copy Section

File: readme.md Copy Chapter

Using Lighthouse in Chrome DevTools Copy Chapter

Using the Chrome extension Copy Chapter

Using the Node CLI Copy Chapter

CLI options Copy Section

Output Examples

Lifecycle Examples

Notes on Error Reporting

Using the Node module Copy Chapter

Viewing a report Copy Chapter

Online Viewer Copy Section

Docs & Recipes Copy Chapter

Develop Copy Chapter

Setup Copy Section

Run Copy Section

Tests Copy Section

Docs Copy Section

Lighthouse Integrations in Web Perf services Copy Chapter

File: README.md

Using Lighthouse in Chrome DevTools

Using the Chrome extension

Using the Node CLI

CLI options

Using the Node module

Viewing a report

Online Viewer

Docs & Recipes

Develop

Setup

Run

Tests

Docs

Lighthouse Integrations in Web Perf services

Lighthouse Integrations in non-Web Perf services

Plugins

Related projects

FAQ

How does Lighthouse work?

Why is the performance score so low? It looks fine to me.

Why does the performance score change so much?

Can I configure the lighthouse run?

How does Lighthouse use network throttling, and how can I make it better?

Are results sent to a remote server?

How do I get localized Lighthouse results via the CLI?

How do I author custom audits to extend Lighthouse?

How do I contribute?

File: Readme.md

Using Lighthouse in Chrome DevTools

Using the Chrome extension

Using the Node CLI

CLI options

Using the Node module

Viewing a report

Online Viewer

Docs & Recipes

Develop

Setup

Run

Tests

Docs

Lighthouse Integrations in Web Perf services

Lighthouse Integrations in non-Web Perf services

Plugins

Related projects

FAQ

How does Lighthouse work?

Why is the performance score so low? It looks fine to me.

Why does the performance score change so much?

Can I configure the lighthouse run?

How does Lighthouse use network throttling, and how can I make it better?

Are results sent to a remote server?

How do I get localized Lighthouse results via the CLI?

How do I author custom audits to extend Lighthouse?

How do I contribute?

File: readme.md

Using Lighthouse in Chrome DevTools

Using the Chrome extension

Using the Node CLI

CLI options

Using the Node module

Viewing a report

Online Viewer

Docs & Recipes

Develop

Setup

Run

Tests

Docs

Lighthouse Integrations in Web Perf services

Lighthouse Integrations in non-Web Perf services

Plugins

Related projects

FAQ

How does Lighthouse work?

Why is the performance score so low? It looks fine to me.

Why does the performance score change so much?

Can I configure the lighthouse run?

How does Lighthouse use network throttling, and how can I make it better?