> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/GoogleChrome/lighthouse/llms.txt
> Use this file to discover all available pages before exploring further.

# Device emulation

> Lighthouse emulates a mobile device by default. Learn how to configure screen emulation, user agent spoofing, and form factor for desktop or real-device testing.

Lighthouse emulates a mobile device by default, applying screen dimensions, device scale factor, and a mobile user agent string. This simulates how a typical mobile user experiences your page, independent of the device running Lighthouse.

<Note>
  "Emulation" in Lighthouse refers specifically to screen and user agent emulation. Network and CPU throttling are covered separately in [Throttling](/configuration/throttling).
</Note>

## Mobile vs desktop

By default, Lighthouse runs in mobile mode. To run with desktop settings and scoring calibration, use the `--preset=desktop` flag.

```bash theme={null}
# Run with desktop emulation and scoring
lighthouse --preset=desktop https://example.com
```

<Tip>
  `--preset=desktop` is the recommended way to test desktop performance. It replaces the older `--emulated-form-factor=desktop` flag, which was removed in Lighthouse v7.
</Tip>

## The `--form-factor` flag

The `formFactor` setting does not control emulation directly. Instead, it tells Lighthouse how to interpret the run — specifically for scoring performance metrics and skipping mobile-only tests when running in desktop mode.

You must always set `formFactor` when configuring emulation externally. The allowed values are `mobile` (default) and `desktop`.

```bash theme={null}
lighthouse --form-factor=desktop https://example.com
```

## Screen emulation

The `screenEmulation` setting controls the viewport applied to the page. It accepts an object with the following fields:

| Field               | Type      | Description                                                               |
| ------------------- | --------- | ------------------------------------------------------------------------- |
| `width`             | `number`  | Viewport width in pixels.                                                 |
| `height`            | `number`  | Viewport height in pixels.                                                |
| `deviceScaleFactor` | `number`  | Device pixel ratio.                                                       |
| `mobile`            | `boolean` | Enables overlay scrollbars and other mobile-specific rendering behaviors. |
| `disabled`          | `boolean` | When `true`, Lighthouse skips applying screen emulation entirely.         |

To disable screen emulation — for example, when running against a real device or when emulation is applied externally by Puppeteer:

```bash theme={null}
lighthouse --screenEmulation.disabled https://example.com
```

## User agent emulation

By default, Lighthouse spoofs a mobile user agent string to ensure pages return their mobile variants. The `emulatedUserAgent` setting controls this behavior.

| Value            | Behavior                                        |
| ---------------- | ----------------------------------------------- |
| `true` (default) | Apply the default Lighthouse user agent string. |
| `false`          | Disable user agent spoofing.                    |
| A string         | Apply the provided user agent string.           |

Disabling user agent spoofing is safe to do redundantly — if the real device is already sending the correct user agent, setting `emulatedUserAgent: false` has no negative effect.

## Testing on a real mobile device

When running Lighthouse against Chrome on an actual mobile device, you should disable Lighthouse's own screen emulation and CPU throttling, since the device provides real conditions.

```bash theme={null}
lighthouse \
  --screenEmulation.disabled \
  --throttling.cpuSlowdownMultiplier=1 \
  https://example.com
```

`--form-factor=mobile` is the default and does not need to be set explicitly in this case.

## Changes in v7

Lighthouse v7 overhauled the emulation configuration to be more explicit and consistent. Key changes:

| Status  | Property                                                                        |
| ------- | ------------------------------------------------------------------------------- |
| Removed | `emulatedFormFactor` — replaced by `formFactor`                                 |
| Removed | `TestedAsMobileDevice` artifact — replaced by explicit `formFactor`             |
| Removed | `internalDisableDeviceScreenEmulation` — replaced by `screenEmulation.disabled` |
| Added   | `formFactor`                                                                    |
| Added   | `screenEmulation`                                                               |
| Added   | `emulatedUserAgent`                                                             |

The `throttling` and `throttlingMethod` settings were not changed in v7.