Lighthouse analyzes web apps and web pages, collecting modern performance metrics and insights on developer best practices.
Lighthouse is integrated directly into the Chrome Developer Tools, under the "Audits" panel.
Installation: install Chrome.
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.
npm install -g lighthouse# or use yarn:# yarn global add lighthouse
By default, Lighthouse writes the report to an HTML file. You can control the output format by passing flags.
$ lighthouse --helplighthouse <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]--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 .--config-path The path to the config JSON.--chrome-flags Custom flags to pass to Chrome . For a full list of flags, seehttp://peter.sh/experiments/chromium-command-line-switches/.Environment variables:CHROME_PATH: Explicit path of intended Chrome binary. If set must point to an executable of a build ofChromium version 54.0 or later. By default, any detected Chrome Canary or Chrome will be launched.[default: ""]--perf Use a performance-test-only configuration [boolean]--port The port to use
lighthouse# saves `./<HOST>_<DATE>.report.html`lighthouse --output json# json output sent to stdoutlighthouse --output html --output-path ./report.html# saves `./report.html`# NOTE: specifying an output path with multiple formats ignores your specified extension for *ALL* formatslighthouse --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.screenshots.html`lighthouse --output-path=./report.json --output json# saves `./report.json`
You can run a subset of Lighthouse's lifecycle if desired via the
-A) CLI flags.
lighthouse -G http://example.com# launches browser, collects artifacts, saves them to disk (in `./latest-run/`) and quitslighthouse -A http://example.com# skips browser interaction, loads artifacts from disk (in `./latest-run/`), runs audits on them, generates reportlighthouse -GA http://example.com# Normal gather + audit run, but also saves collected artifacts to disk for subsequent -A runs.
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.
Lighthouse can produce a report as JSON or HTML.
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
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.
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 firstgit clone https://github.com/GoogleChrome/lighthousecd lighthouseyarnyarn install-allyarn build-all# The CLI is authored in TypeScript and requires compilation.# If you need to make changes to the CLI, run the TS compiler in watch mode:# cd lighthouse-cli && 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 filesyarn test# watch for file changes and run tests# Requires : brew install entryarn watch## run linting, unit, and smoke tests separatelyyarn lintyarn unityarn smoke## run closure compiler (on whitelisted files)yarn closure## import your report renderer into devtools-frontend and run devtools closure compileryarn compile-devtools
This section details projects that have integrated Lighthouse. 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
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. Calibre comes with a free 14-day trial.
Greta Lighthouse - Greta Lighthouse is a tool that lets you run free Lighthouse tests from anywhere in the world. It provides insights into your users' perceived performance and recommendations on how to improve. The tool considers parameters such as location and type of device to simulate real user conditions. Greta also provides a new type of platform that helps companies understand, control, and improve their users’ experience via an innovative approach to content delivery.
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.
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.
Yes! Details in Lighthouse configuration.
Good question. Network and CPU throttling are applied by default in a Lighthouse run. The network
attempts to emulate 3G 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
--disable-* flags mentioned above.
Read more in our guide to network throttling.
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.