#  `add_images`

Stamp user-specified images onto PDF pages
## Usage
> pdftl `<input>` `add_images` `<spec>...` `output` `<file>`

## Details
Add user-specified images to PDF pages as overlays or underlays.

An image rule specification has the format:

>  `[page range]<delimiter><image path(s)><delimiter>[<options>]`

`<delimiter>` must be a single, non-alphanumeric character (e.g., /, !, #).
Multiple image paths within delimiters can be separated by spaces or commas.

### Options

Options are passed as comma-separated key=value pairs inside
parentheses, e.g., (`position=top-right`, `scale_mode=fit`, `opacity=0.5`).

#### Positioning and Layout Options

* `underlay=<true|false>`: Draw the image behind the page contents instead of on top.
  Default: `false`.

* `scale_mode=<stretch|fit|fill|none>`: Aspect ratio preservation logic.
  Default: `none`.

* `position=<keyword>`: Preset position (top-left, center, bottom-right, etc.).
  Default: `bottom-left`.

* `width=<dim>`, `height=<dim>`: Dimensions with a unit (e.g., `10cm`, `2in`, `150pt`).

* `offset-x=<dim>`, `offset-y=<dim>`: Extra offset displacement relative to the anchor position.
  Default: `0`.

* `opacity=<float>`: Transparency setting between 0.0 (transparent) and 1.0 (opaque).
  Default: `1.0`.
## Examples

> Stamp a logo on the top right of all pages
```
pdftl in.pdf add_images '/logo.png/(position=top-right, width=5cm, offset-x=-0.5cm, offset-y=-0.5cm)' output out.pdf
```

> Add a background underlay image to even pages, scaling to fill
```
pdftl in.pdf add_images 'even!background.jpg!(underlay=true, scale_mode=fill)' output out.pdf
```

> Overlay a semi-transparent watermark centered on page 1
```
pdftl in.pdf add_images '1#watermark.png#(position=center, opacity=0.3, width=200pt)' output out.pdf
```


**Tags**: in_place, images, overlay, underlay

*Source: pdftl.operations.add_images*

*Read online: [https://pdftl.readthedocs.io/en/latest/operations/add_images.html](https://pdftl.readthedocs.io/en/latest/operations/add_images.html)*

*Type: Operation*