Configuration overview

Customize Lighthouse by passing a config object to control which audits run, how they are scored, and what settings apply.

The Lighthouse config object is the primary way to customize a Lighthouse run. You can use it to limit which audits run, add custom checks, adjust throttling, tweak scoring, and more.

Passing a config

1. Create a config file

   Create a JavaScript file that exports your config object. Most configs extend lighthouse:default to inherit the full default set of audits, artifacts, and categories.

   custom-config.js

   export default {
     extends: 'lighthouse:default',
     settings: {
       onlyAudits: [
         'speed-index',
         'interactive',
       ],
     },
   };
   
2. Pass the config to Lighthouse

   Use the --config-path flag when running from the CLI, or pass the config as the third argument when using the Node API.

   CLI

   lighthouse --config-path=path/to/custom-config.js https://example.com
   

   Node API

   import lighthouse from 'lighthouse';
   import config from './path/to/custom-config.js';
   
   await lighthouse('https://example.com/', { port: 9222 }, config);
   

Config properties

Property	Type	Description
extends	string | undefined	Inherit from a built-in config. Only 'lighthouse:default' is supported.
settings	Object | undefined	Control runtime options such as throttling and which audits to run.
artifacts	Object[]	List of artifacts (data gathered from the page) to collect.
audits	string[]	Audits to run against the collected artifacts.
categories	Object | undefined	How to group and score audits in the report.
groups	Object | undefined	Visual groupings of audits within a category.
plugins	string[]	Plugin packages to include, which can add their own audits.

extends

Setting extends: 'lighthouse:default' makes your config inherit the default artifacts, audits, groups, and categories. You can then add to or override only what you need.

Config extension is the recommended approach for running custom Lighthouse. Without extends, you must define all artifacts and audits yourself.

export default {
  extends: 'lighthouse:default',
  settings: {
    skipAudits: ['uses-http2'],
  },
};

extends only supports 'lighthouse:default'. To use other built-in presets such as perf, desktop, or experimental, use the --preset CLI flag or import the config file directly.

settings

The settings object controls runtime behavior. The most commonly used options are:

Option	Type	Description
onlyCategories	string[]	Run only the specified categories. Additive with onlyAudits. Reduces total audit time.
onlyAudits	string[]	Run only the specified audits. Additive with onlyCategories. Reduces total audit time.
skipAudits	string[]	Exclude the specified audits. Takes priority over onlyCategories. Not usable alongside onlyAudits.

export default {
  extends: 'lighthouse:default',
  settings: {
    onlyCategories: ['performance'],
    skipAudits: ['uses-http2'],
  },
};

For the full list of settings options, see the configuration reference.

artifacts

Artifacts are the raw data gathered from a page load. Each artifact is produced by a gatherer. On extension, artifacts are concatenated with the defaults.

Field	Type	Description
id	string	Unique identifier used to reference this artifact in audits.
gatherer	string	The gatherer module that produces this artifact.

{
  artifacts: [
    { id: 'Accessibility', gatherer: 'accessibility' },
    { id: 'AnchorElements', gatherer: 'anchor-elements' },
  ],
}

audits

The list of audit modules to run. Audits receive artifacts and produce scored results.

{
  audits: [
    'first-contentful-paint',
    'byte-efficiency/unminified-css',
  ],
}

categories

Categories group audits and produce an overall score. Each category entry appears in the Lighthouse report with an aggregate score.

Field	Type	Description
title	string	Display name of the category.
description	string	Description shown in the report.
auditRefs	Object[]	Audits to include in this category.
auditRefs[$i].id	string	The audit ID to include.
auditRefs[$i].weight	number	Scoring weight for this audit within the category.
auditRefs[$i].group	string (optional)	Display group ID for this audit.

{
  categories: {
    performance: {
      title: 'Performance',
      auditRefs: [
        { id: 'first-contentful-paint', weight: 3, group: 'metrics' },
        { id: 'interactive', weight: 5, group: 'metrics' },
      ],
    },
  },
}

Many tools that consume Lighthouse do not need to group or score audit results. In those cases, omitting categories is fine.

groups

Groups control how audits are visually organized within a category in the report.

The report renderer has hardcoded display logic tied to specific group names. Adding arbitrary groups without matching renderer logic may not display as expected.

{
  groups: {
    metrics: {
      title: 'Metrics',
      description: 'These metrics encapsulate your web app\'s performance across a number of dimensions.',
    },
  },
}

Built-in presets

Lighthouse ships with several preset configs you can use via the --preset CLI flag:

Preset	Description
perf	Runs only performance audits for faster results.
desktop	Applies desktop viewport and scoring calibration instead of the default mobile emulation.
experimental	Enables experimental audits not yet in the default config.

# Run with the desktop preset
lighthouse --preset=desktop https://example.com

# Run with the perf preset
lighthouse --preset=perf https://example.com

Config extension

Config extension lets you build on the default Lighthouse setup with minimal boilerplate. When extends: 'lighthouse:default' is set, the default artifacts, audits, groups, and categories are automatically included. You only need to specify what you want to change.

custom-config.js

export default {
  extends: 'lighthouse:default',
  settings: {
    onlyCategories: ['performance', 'accessibility'],
  },
  audits: [
    // add custom audits here
  ],
};

For more on the full config schema, see the configuration reference.