Using the Unlighthouse CLI is the primary way to scan entire production sites.


  • Accurate Performance Metrics
  • Minimal configuration


Public Early Access 🎉

Unlighthouse is currently in public early access, made possible by my sponsors 💖. Please consider becoming a sponsor or following me @harlan_zw 🐦if you like this project.


Single run

If you prefer not to add a global dependency you can run Unlighthouse once off.

Using pnpm dlx (recommended) - requires pnpm.

pnpm dlx unlighthouse --site <your-site>
# or if that doesn't work try:
# pnpm dlx unlighthouse-puppeteer --site

Using npx

npx unlighthouse --site <your-site>
# or if that doesn't work try:
# npx unlighthouse-puppeteer --site

With Chrome Dependency

Unlighthouse aims to keep the installation size small, for this reason it depends natively on your locally installed chrome.

If you get errors about puppeteer or chrome not being available, the easiest way to resolve it is with the unlighthouse-puppeteer binary.

unlighthouse-puppeteer --site

You will need to use unlighthouse-puppeteer anywhere it says unlighthouse.


Once installed globally you'll have access to Unlighthouse through the unlighthouse binary.

Do a the default scan.

unlighthouse --site --debug

Run without caching, throttle the requests and do 3 samples.

unlighthouse --site --debug --no-cache --throttle --samples 3


Configuring the CLI can be done either through the CLI arguments or through a config file.

See the Configuration section for more details and the guides.

CLI Options

-v, --versionDisplay version number.
--site <url>Host URL to scan.
--root <path>Define the project root.
--config-file <path>Path to config file.
--output-path <path>Path to save the contents of the client and reports to.
--cacheEnable the caching.
--no-cacheDisable the caching.
--desktopSimulate device as desktop.
--mobileSimulate device as mobile.
--throttleEnable the throttling.
--samplesSpecify the amount of samples to run.
--urlsSpecify explicit relative URLs as a comma-seperated list.
e.g. unlighthouse --site --urls /guide,/api,/config
--enable-javascriptWhen inspecting the HTML wait for the javascript to execute. Useful for SPAs.
--disable-javascriptWhen inspecting the HTML, don't wait for the javascript to execute.
--enable-i18n-pagesEnable scanning pages which use x-default.
--disable-i18n-pagesDisable scanning pages which use x-default.
-d, --debugDebug. Enable debugging in the logger.
-h, --helpDisplay available CLI options

Config File

If you want to configure Unlighthouse, you can create a unlighthouse.config.ts file in your cwd.


export default {
  site: '',
  debug: true,
  scanner: {
    device: 'desktop'