Skip to main content
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.
lighthouse --config-path=path/to/custom-config.js https://example.com

​
Config properties

PropertyTypeDescription
extendsstring | undefinedInherit from a built-in config. Only 'lighthouse:default' is supported.
settingsObject | undefinedControl runtime options such as throttling and which audits to run.
artifactsObject[]List of artifacts (data gathered from the page) to collect.
auditsstring[]Audits to run against the collected artifacts.
categoriesObject | undefinedHow to group and score audits in the report.
groupsObject | undefinedVisual groupings of audits within a category.
pluginsstring[]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:
OptionTypeDescription
onlyCategoriesstring[]Run only the specified categories. Additive with onlyAudits. Reduces total audit time.
onlyAuditsstring[]Run only the specified audits. Additive with onlyCategories. Reduces total audit time.
skipAuditsstring[]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.
FieldTypeDescription
idstringUnique identifier used to reference this artifact in audits.
gathererstringThe 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.
FieldTypeDescription
titlestringDisplay name of the category.
descriptionstringDescription shown in the report.
auditRefsObject[]Audits to include in this category.
auditRefs[$i].idstringThe audit ID to include.
auditRefs[$i].weightnumberScoring weight for this audit within the category.
auditRefs[$i].groupstring (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:
PresetDescription
perfRuns only performance audits for faster results.
desktopApplies desktop viewport and scoring calibration instead of the default mobile emulation.
experimentalEnables 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.

Build docs developers (and LLMs) love

Get started for freeTalk to us