How to run Lighthouse on localhost

Three ways to run it

$ npx lighthouse http://localhost:3000 --view

# desktop preset, performance only, JSON on disk
$ npx lighthouse http://localhost:3000 \
    --preset=desktop \
    --only-categories=performance \
    --output=json --output-path=./report.json

# headless, for a script or a CI step
$ npx lighthouse http://localhost:3000 \
    --chrome-flags="--headless=new"

# match the DevTools panel defaults exactly
$ npx lighthouse http://localhost:3000 \
    --throttling-method=simulate --form-factor=mobile

import lighthouse from 'lighthouse';
import * as chromeLauncher from 'chrome-launcher';

const chrome = await chromeLauncher.launch({
  chromeFlags: ['--headless=new'],
});

const result = await lighthouse('http://localhost:3000', {
  port: chrome.port,
  output: 'json',
  onlyCategories: ['performance'],
});

const { categories, audits } = result.lhr;
console.log('Performance', categories.performance.score * 100);
console.log('LCP', audits['largest-contentful-paint'].displayValue);

await chrome.kill();

Why a localhost score is usually wrong

Lighthouse will happily give you a number for a local page. Four things make that number diverge from what the same code does in production, and they mostly push in the same direction: optimistic.

01. A dev server is not your site

This is the big one, and it pushes the other way. A development server serves unminified bundles, an inline hot module replacement client, source maps, and framework development warnings, usually with no compression. None of it reaches users, all of it hurts the score, and it is entirely an artefact of the server you happen to be running.

Always audit a production build. Build it, serve the build, then audit that:

$ npm run build
$ npm start          # or: npx serve ./dist
$ npx lighthouse http://localhost:3000 --view

02. Localhost has no network

Round trip time to your own machine is effectively zero. There is no DNS lookup, no TLS handshake, no last-mile latency, and no CDN in front. Time to first byte is close to instant, which flatters First Contentful Paint and Largest Contentful Paint. Lighthouse's simulated throttling models a slow connection on top of what it measured, but it cannot model infrastructure that is not there.

03. Your CPU is not a phone

Lighthouse's mobile preset applies a flat 4x CPU slowdown, chosen so that a mid-range desktop lands roughly on mid-tier mobile. That multiplier is a fixed constant, not a measurement. On a fast laptop, 4x under-throttles: the emulated device ends up considerably quicker than the phone it is standing in for, Total Blocking Time reads low, and Performance reads high. Lighthouse records what it thinks of your machine as benchmarkIndex in the JSON, but nothing acts on it for you.

04. One run is an anecdote

Performance scores commonly move about 5 points between identical runs of an unchanged page. Total Blocking Time is the most volatile input and carries roughly 30 percent of the Performance score, and it responds to whatever else your CPU is doing: a build in another terminal, a sync client, a browser tab playing video. If you change something and the score moves 4 points, you have learned nothing.

Local versus production, factor by factor

Making a local number mean something

You cannot make a local audit predict production. You can make it a reliable instrument for detecting change, which is what you actually want while you are writing code.

1. Audit a production build. Everything else is noise on top of a broken measurement.
2. Take the median of three to five runs. Lighthouse ships computeMedianRun for exactly this. A single run cannot distinguish a real regression from CPU jitter.
3. Calibrate the CPU throttle. Read your host's benchmarkIndex and pick a multiplier that actually lands on mid-tier mobile from your hardware, rather than trusting the default 4x.
4. Hold the environment still. Same machine, same power state, nothing heavy in the background, no extensions. A laptop on battery throttles its own CPU and will quietly change your results.
5. Compare like with like. Track local against local over time. Use production numbers to answer "how are we doing" and local numbers to answer "did this change help".

The LightAudit Score console does the repetition, calibration and history automatically, and flags when the machine rather than the page moved the score. But the discipline matters more than the tool: a median of five runs from the CLI beats a single run from anything.

What you still cannot get locally

Lighthouse gives you lab data: one controlled run in a simulated environment. It does not give you field data, the Core Web Vitals that real Chrome users actually experienced, because that comes from the Chrome UX Report and requires a public origin with enough real traffic to report on. No local tool can produce it for localhost, and none ever will.

If what you actually wanted was PageSpeed Insights against a local address, that is a different and slightly worse problem: PSI cannot reach localhost at all, because it fetches your URL from Google's own network.

Frequently asked questions