Lighthouse v3 Migration Guide  |  Chrome for Developers
Skip to main content
Docs
Build with Chrome
Learn how Chrome works, participate in origin trials, and build with Chrome everywhere.
Web Platform
Capabilities
ChromeDriver
Extensions
Chrome Web Store
Chromium
Web on Android
Origin trials
Release notes
Productivity
Create the best experience for your users with the web's best tools.
DevTools
Lighthouse
Chrome UX Report
Accessibility
Modern Web Guidance
Get things done quicker and neater, with our ready-made libraries.
Workbox
Puppeteer
Experience
Design a beautiful and performant web with Chrome.
AI
Performance
CSS and UI
Identity
Payments
Privacy and security
Resources
More from Chrome and Google.
All documentation
Baseline
web.dev
PageSpeed Insights audit
Isolated Web Apps (IWA)
Case studies
Blog
New in Chrome
/
English
Deutsch
Español – América Latina
Français
Indonesia
Italiano
Nederlands
Polski
Português – Brasil
Tiếng Việt
Türkçe
Русский
עברית
العربيّة
فارسی
हिंदी
বাংলা
ภาษาไทย
中文 – 简体
中文 – 繁體
日本語
한국어
Sign in
Docs
Lighthouse
Lighthouse
Get started
Performance audits
Accessibility audits
Best Practices audits
SEO audits
Agentic browsing audits
Docs
More
Lighthouse
Get started
Performance audits
Accessibility audits
Best Practices audits
SEO audits
Agentic browsing audits
Case studies
Blog
New in Chrome
Overview
Performance
Performance audit scoring
Metrics
First Contentful Paint
Speed Index
Total Blocking Time
Largest Contentful Paint
Cumulative Layout Shift
Insights
CSS selector costs
Document request latency
Duplicated JavaScript
Font display
Forced reflow
Improve image delivery
INP breakdown
Layout shift culprits
LCP breakdown
LCP request discovery
Legacy JavaScript
Modern HTTP
Network dependency tree
Optimize DOM size
Optimize viewport for mobile
Render-blocking requests
3rd parties
Use efficient cache lifetimes
Diagnostics
Avoid enormous network payloads
Avoid non-composited animations
Defer offscreen images
Ensure the page can be restored from the back/forward cache
Keep request counts low and transfer sizes small
Lazy load third-party resources with facades
Minify CSS
Minify JavaScript
Minimize main thread work
Preload key requests
Reduce JavaScript execution time
Remove unused CSS
User Timing marks and measures
Retired Metrics
Time to Interactive
First Meaningful Paint
First CPU Idle
Max Potential First Input Delay
Accessibility
Accessibility audit scoring
Manual checks
Custom controls have ARIA roles
Custom controls have associated labels
Trapped user focus
Interactive controls are keyboard-focusable
Interactive elements indicate their purpose and state
The page has a logical tab order
The user's focus is directed to new content added to the page
Offscreen content is hidden from assistive technology
HTML5 landmark elements are used to improve navigation
Visual order on the page follows DOM order
Learn Accessibility
Best practices audit
General best practices
Page lacks the HTML doctype, thus triggering quirks mode
Browser errors were logged to the console
Displays images with incorrect aspect ratio
Charset declaration is missing or occurs too late in the HTML
Make your page fast
Uses document.write()
Use passive listeners to improve scrolling performance
Make your page secure
Links to cross-origin destinations are unsafe
Includes front-end JavaScript libraries with known security vulnerabilities
Ensure CSP is effective against XSS attacks
Does not use HTTPS
Does not redirect HTTP traffic to HTTPS
Use a strong HSTS policy
Mitigate clickjacking with XFO or CSP
Mitigate Dom-Based XSS with Trusted Types
Create a good user experience
Requests the notification permission on page load
Requests the geolocation permission on page load
Prevents users from pasting into input fields
Avoid deprecated technologies
Uses Application Cache
Uses deprecated APIs
Diagnostic audits
Detected JavaScript libraries
SEO
Help search engines understand your content
Document does not have a meta description
Links do not have descriptive text
Document doesn't have a valid hreflang
Document does not have a valid rel=canonical
Help search engines crawl and index
Page has unsuccessful HTTP status code
robots.txt is not valid
Document uses plugins
Mobile friendly changes
Document doesn't use legible font sizes
Tap targets are not sized appropriately
Manual checks
Structured data is valid
Agentic browsing
Agentic browsing scoring
WebMCP integration
Registered WebMCP tools
Forms missing declarative WebMCP
WebMCP schema validity
Discoverability
llms.txt
Accessibility
Accessibility for agents
Layout stability
Layout stability
Migrations
Lighthouse v3 Migration Guide
Build with Chrome
Web Platform
Capabilities
ChromeDriver
Extensions
Chrome Web Store
Chromium
Web on Android
Origin trials
Release notes
Productivity
DevTools
Lighthouse
Chrome UX Report
Accessibility
Modern Web Guidance
Workbox
Puppeteer
Experience
AI
Performance
CSS and UI
Identity
Payments
Privacy and security
Resources
All documentation
Baseline
web.dev
PageSpeed Insights audit
Isolated Web Apps (IWA)
Home
Docs
Lighthouse
Get started
Lighthouse v3 Migration Guide
Stay organized with collections
Save and categorize content based on your preferences.
This guide is for Lighthouse v2 users who:
Run Lighthouse from Node or the command line.
Rely on the JSON output of Lighthouse.
If these do not apply to you, then your workflow for running Lighthouse is mostly the same. See Announcing Lighthouse 3.0 for an overview of new features and changes.
Invocation changes
Lighthouse now computes simulated performance by default and throttling settings have been heavily changed.
CLI Flags
Scenario
v2 Flags
v3 Flags
DevTools 3G Throttling
None (default behavior)
--throttling-method=devtools
No Throttling
--disable-network-throttling --disable-cpu-throttling
--throttling-method=provided
Network Throttling, No CPU Throttling
--disable-cpu-throttling
--throttling-method=devtools --throttling.cpuSlowdownMultiplier=1
Run Performance Audits
--perf
--preset=perf
Run Mixed Content Audits
--mixed-content
--preset=mixed-content
Node Module
In Lighthouse v3, the Node module accepts the same configuration options as the CLI. This is a breaking change in the sense that many of these options were ignored in v2, whereas now they'll actually affect how Lighthouse runs.
const fs = require('fs');
const lighthouse = require('lighthouse');
async function run() {
// `onlyCategories` was previously only available as a config setting.
// `output` was previously only available in CLI.
const flags = {onlyCategories: ['performance'], output: 'html'};
const html = (await lighthouse('https://google.com/', flags)).report;
fs.writeFileSync('report.html', html);
}
Output changes
New, top-level format in JSON output
The JSON object that Lighthouse v3 returns now contains three top-level properties:
lhr. The results of the audits. Short for "Lighthouse Results". This was essentially the top-level object in v2, but v3 introduces breaking changes to the shape of this object, too. See Changes to the results object.
artifacts. The data collected from Chrome while auditing. This was previously intermingled with the properties of the LHR.
report. The formatted report HTML/JSON/CSV as a string.
Changes to the results object
As mentioned in New, top-level format in JSON output, the results of audits are no available via the lhr property. In v2, the contents of this object were essentially the top-level JSON output. However, the shape of this object itself has changed in v3. The table below lists all the changes.
If a row has a value in both v2 and v3 columns, it means that you should replace any reference to the v2 property in your code with the v3-equivalent.
When a row does not have a value in the v3 column, the Notes column describes your options.
Note that items such as ID represent placeholder text.
v2 Property
v3-Equivalent
Notes
initialUrl
requestedUrl
url
finalUrl
generatedTime
fetchedTime
reportCategories
categories
Changed from array to a keyed object.
reportGroups
categoryGroups
audits.ID.name
audits.ID.id
audits.ID.description
audits.ID.title
audits.ID.helpText
audits.ID.description
audits.ID.scoringMode
audits.ID.scoreDisplayMode
Possible values have been expanded to
numeric|binary|manual|informative|not-applicable|error.
audits.ID.score
audits.ID.score
Scores are always a number between 0 and 1 (not 0-100) when scoreDisplayMode is
numeric or binary. Scores are always null for other display modes as there is no
notion of pass/fail.
audits.ID.displayValue
audits.ID.displayValue
Can now be an array of printf-style arguments for string interpolation.
audits.ID.debugString
audits.ID.explanation
audits.ID.errorMessage
audits.ID.warnings
debugString values have been converted to one of the three properties above
depending on their intent.
audits.ID.details
audits.ID.details
Structure of details has shifted to be more consumable. Each entry in .items
is an object with reliable keys instead of any[].
audits.ID.error
audits.ID.scoreDisplayMode === 'error'
audits.ID.notApplicable
audits.ID.scoreDisplayMode === 'not-applicable'
audits.ID.informative
audits.ID.scoreDisplayMode === 'informative'
audits.ID.manual
audits.ID.scoreDisplayMode === 'manual'
audits.ID.extendedInfo
Removed. Use details instead.
Except as otherwise noted, the content of this page is licensed under the Creative Commons Attribution 4.0 License, and code samples are licensed under the Apache 2.0 License. For details, see the Google Developers Site Policies. Java is a registered trademark of Oracle and/or its affiliates.
Last updated 2018-05-08 UTC.
[[["Easy to understand","easyToUnderstand","thumb-up"],["Solved my problem","solvedMyProblem","thumb-up"],["Other","otherUp","thumb-up"]],[["Missing the information I need","missingTheInformationINeed","thumb-down"],["Too complicated / too many steps","tooComplicatedTooManySteps","thumb-down"],["Out of date","outOfDate","thumb-down"],["Samples / code issue","samplesCodeIssue","thumb-down"],["Other","otherDown","thumb-down"]],["Last updated 2018-05-08 UTC."],[],[]]
Contribute
File a bug
See open issues
Related content
Chromium updates
Case studies
Archive
Podcasts & shows
Follow
@ChromiumDev on X
YouTube
Chrome for Developers on LinkedIn
RSS
Terms
Privacy
Manage cookies
English
Deutsch
Español – América Latina
Français
Indonesia
Italiano
Nederlands
Polski
Português – Brasil
Tiếng Việt
Türkçe
Русский
עברית
العربيّة
فارسی
हिंदी
বাংলা
ภาษาไทย
中文 – 简体
中文 – 繁體
日本語
한국어