---
title: "dpi parameter"
description: "Render at 1x to 4x for retina displays. Memory and timeout implications explained."
url: "https://html2img.com/docs/parameters/dpi/"
---

# DPI Parameter

The `dpi` parameter (Device Pixel Ratio) controls the resolution of the generated image.

> **Note**
>
> `dpi` is ignored when [`format`](https://html2img.com/docs/parameters/format/) is `pdf`, because vector output is already sharp at any zoom level.

## Specifications

| Property | Value |
|----------|-------|
| Type | integer |
| Required | No |
| Default | 1 (Screenshot API), 2 (HTML API) |
| Range | 1-4 |
| API | Both HTML/CSS and Screenshot APIs |

## Description

The DPI parameter:
- Controls the image resolution
- Affects the final image size
- Impacts processing time and memory usage
- Determines the clarity of text and graphics

> **Important**
>
> Higher DPI values significantly increase processing time and memory usage. For most use cases, a DPI of 1 or 2 provides sufficient quality.

> **Warning**
>
> When setting `fullpage` to `true` the DPI value will be forced to `1`. If you need a larger DPI then set explicit `width` and `height` instead.

> **Warning**
>
> When using DPI values greater than 1, remember that the actual rendered dimensions will be multiplied by the DPI value. For example, a canvas with width=800 and DPI=2 will be rendered at 1600px wide. If you specify width and height parameters, you should either:
> - Divide your dimensions by the DPI value (e.g. halve them for DPI=2) so the output lands at your target size
> - Or omit width/height to let the image scale naturally with DPI

## Examples

### Basic Screenshot (Default DPI)
```json
{
    "url": "https://example.com"
}
```

### High Resolution HTML Capture
```json
{
    "html": "<div>High Quality Text</div>",
    "dpi": 2
}
```

### Maximum Quality Screenshot
```json
{
    "url": "https://example.com",
    "dpi": 4,
    "webhook_url": "https://your-domain.com/webhook"
}
```

## DPI Value Guide

| DPI | Use Case | Notes |
|-----|-----------|-------|
| 1 | Quick screenshots, previews | Fastest processing, smallest file size |
| 2 | Standard quality, most use cases | Good balance of quality and performance |
| 3 | High quality, printing | Larger files, slower processing |
| 4 | Maximum quality | Very large files, significantly slower |

> **Warning**
>
> When using DPI values of 3 or 4:
> - Always use the `webhook_url` parameter
> - Expect longer processing times
> - Be prepared for larger file sizes

## Best Practices

1. **Choose the Right DPI**
 - Use DPI 1 for thumbnails and previews
 - Use DPI 2 for standard web use
 - Use DPI 3-4 only when high resolution is required

2. **Optimize Performance**
 - Combine with appropriate viewport dimensions
 - Use webhooks for high DPI captures
 - Consider file size requirements

3. **Testing**
 - Test different DPI values with your content
 - Check file sizes and quality
 - Monitor processing times

> **Note**
>
> The HTML API defaults to DPI 2 for sharper text rendering, while the Screenshot API defaults to DPI 1 for faster processing.

## Common values

- **1** - default for screenshots. Fastest, smallest files, plenty for thumbnails and previews.
- **2** - retina output. Doubles memory and time, but produces files sized for high-DPI displays without manual scaling.
- **3** - rare, only for print. Use `webhook_url` to avoid the 30 second sync timeout.
- **4** - the maximum. Very large files and the slowest renders; only with `webhook_url`.

## When to use

Default to 1 unless you are rendering for a retina display target. Use 2 for any image that will appear in a UI on modern phones or laptops. Reach for 3 only for printed output or marketing assets that need to scale beyond a standard screen.

## Common mistakes

- **Combining `dpi: 3` with sync requests.** The render usually exceeds the 30 second budget. Always pair high DPI with [webhook_url](https://html2img.com/docs/parameters/webhook-url/).
- **Forgetting that DPI multiplies dimensions.** A `width: 1200, dpi: 2` produces a 2400px wide PNG. See [dimensions](https://html2img.com/docs/parameters/dimensions/) for sizing guidance.

See also: [chart-screenshot example](https://html2img.com/docs/examples/chart-screenshot/), [invoice-receipt example](https://html2img.com/docs/examples/invoice-receipt/), and the [getting started guide](https://html2img.com/docs/getting-started/).

## Templates that use this parameter

Higher DPI is most useful when the rendered image is printed or zoomed. These templates rely on DPI for sharp output:

- [Certificate of completion template](https://html2img.com/templates/certificate-of-completion/)
- [Invoice image template](https://html2img.com/templates/invoice-image/)
- [Receipt image template](https://html2img.com/templates/receipt-image/)
- [Business card template](https://html2img.com/templates/business-card/)
- [Event ticket template](https://html2img.com/templates/event-ticket/)