IMG2PDF(1)

📦
version 0.6.2 · 5 versions
, in ubuntu resolute, ubuntu stonking

💖 IMG2PDF 💖

okay bestie, welcome to img2pdf — she's a User Command and she does exactly one thing and she does it flawlessly: lossless conversion of raster images to pdf. no re-encoding, no quality loss, no drama. periodt. 👑

✨ NAME ✨

img2pdf — lossless conversion of raster images to pdf 🦋

✨ DESCRIPTION ✨

so here's the whole vibe, literally the entire usage line, no cap:

usage: img2pdf [-h] [-v] [-V] [--from-file FILE] [-o out] [-C
colorspace]

       [-D] [--engine engine] [--first-frame-only]
       [--include-thumbnails] [--pillow-limit-break] [--pdfa [PDFA]] [-S
       LxL] [-s LxL] [-b L[:L]] [-f FIT] [-a] [-r ROT] [--crop-border
       L[:L]] [--bleed-border L[:L]] [--trim-border L[:L]] [--art-border
       L[:L]] [--title title] [--author author] [--creator creator]
       [--producer producer] [--creationdate creationdate] [--moddate
       moddate] [--subject subject] [--keywords kw [kw ...]]
       [--viewer-panes PANES] [--viewer-initial-page NUM]
       [--viewer-magnification MAG] [--viewer-page-layout LAYOUT]
       [--viewer-fit-window] [--viewer-center-window]
       [--viewer-fullscreen] [infile ...]

Losslessly convert raster images to PDF without re-encoding PNG, JPEG, and JPEG2000 images. 🫶 That means: the conversion of PNG, JPEG and JPEG2000 images is lossless, and the only extra file size you're getting is from the PDF container itself. iconic behavior honestly.

Other raster graphics formats? they get losslessly stored using the same encoding that PNG uses. ✨

And for images with transparency, the alpha channel gets stored as a separate soft mask. This is lossless, too. 💅

The output is sent to standard output so you can redirect it into a file or pipe it into another program as part of a shell pipe. Want to write the output directly into a file instead? use the -o or --output option, bestie. 🎀

✨ OPTIONS ✨

🎀 positional arguments:

  • infile — Specifies the input file(s) in any format that can be read by the Python Imaging Library (PIL). If no input images are given, then a single image is read from standard input. The special filename - can be used once to read an image from standard input. Wanna read a file in the current directory with the filename - (or with a filename starting with -)? pass it to img2pdf by explicitly stating its relative path like ./-. 🦋 Cannot be used together with --from-file.

💅 options:

  • -h, --help — show this help message and exit. classic.
  • -v, --verbose — Makes the program operate in verbose mode, printing messages on standard error. she's chatty, we love her 💜
  • -V, --version — Prints version information and exits. bye bestie 👋
  • --from-file FILE — Read the list of images from FILE instead of passing them as positional arguments. If this option is used, then the list of positional arguments must be empty. The paths to the input images in FILE are separated by NUL bytes. If FILE is - then the paths are expected on standard input. This option is useful if you want to pass more images than the maximum command length of your shell permits. slay. This option can be used with commands like find -print0. 🔥

🌈 General output arguments:

Arguments controlling the output format. it's giving formatting era.

  • -o, --output out — Makes the program output to a file instead of standard output. no more piping, just vibes ✨
  • -C, --colorspace colorspace — Forces the PIL colorspace. See the epilogue for a list of possible values. Usually the PDF colorspace would be derived from the color space of the input image. This option overwrites the automatically detected colorspace from the input image and thus forces a certain colorspace in the output PDF /ColorSpace property. This is useful for JPEG 2000 images with a different colorspace than RGB. 👑
  • -D, --nodate — Suppresses timestamps in the output and thus makes the output deterministic between individual runs. You can also manually set a date using the --moddate and --creationdate options. reproducible queen 💅
  • --engine engine — Choose PDF engine. Can be either internal, pikepdf or pdfrw.
    • The internal engine does not have additional requirements and writes out a human readable PDF.
    • The pikepdf engine requires the pikepdf Python module and qpdf library, is most featureful, can linearize PDFs ("fast web view") and can compress more parts of it.
    • The pdfrw engine requires the pdfrw Python module but does not support unicode metadata (See https://github.com/pmaupin/pdfrw/issues/39) or palette data (See https://github.com/pmaupin/pdfrw/issues/128).
  • --first-frame-only — By default, img2pdf will convert multi-frame images like multi-page TIFF or animated GIF images to one page per frame. This option will only let the first frame of every multi-frame input image be converted into a page in the resulting PDF. 🎬
  • --include-thumbnails — Some multi-frame formats like MPO carry a main image and one or more scaled-down copies of the main image (thumbnails). In such a case, img2pdf will only include the main image and not create additional pages for each of the thumbnails. If this option is set, img2pdf will instead create one page per frame and thus store each thumbnail on its own page. 🙈
  • --pillow-limit-break — img2pdf uses the Python Imaging Library Pillow to read input images. Pillow limits the maximum input image size to 89478485 pixels to prevent decompression bomb denial of service attacks. If your input image contains more pixels than that, use this option to disable this safety measure during this run of img2pdf. ⚠️
okay so real talk: that Pillow limit is a safety measure against decompression bombs, and this flag turns it OFF. dramatic, dangerous, your call. 😭
  • --pdfa [PDFA] — Output a PDF/A-1b compliant document. By default, this will embed either /usr/share/color/icc/sRGB.icc, /usr/share/color/icc/OpenICC/sRGB.icc or /usr/share/color/icc/colord/sRGB.icc as the color profile, whichever is found to exist first. archival girlie 📄✨

🦋 Image and page size and layout arguments:

Every input image will be placed on its own page. The image size is controlled by the dpi value of the input image or, if unset or missing, the default dpi of 96.00. By default, each page will have the same size as the image it shows. Thus, there will be no visible border between the image and the page border by default. If image size and page size are made different from each other by the options in this section, the image will always be centered in both dimensions. 💅

The image size and page size can be explicitly set using the --imgsize and --pagesize options, respectively. If either dimension of the image size is specified but the same dimension of the page size is not, then the latter will be derived from the former using an optional minimal distance between the image and the page border (given by the --border option) and/or a certain fitting strategy (given by the --fit option). The converse happens if a dimension of the page size is set but the same dimension of the image size is not. 🔄

Any length value in below options is represented by the meta variable L which is a floating point value with an optional unit appended (without a space between them). The default unit is pt (1/72 inch, the PDF unit) and other allowed units are cm (centimeter), mm (millimeter), and in (inch). 📏

Any size argument of the format LxL in the options below specifies the width and height of a rectangle where the first L represents the width and the second L represents the height with an optional unit following each value as described above. Either width or height may be omitted. If the height is omitted, the separating x can be omitted as well. Omitting the width requires to prefix the height with the separating x. The missing dimension will be chosen so to not change the image aspect ratio. Instead of giving the width and height explicitly, you may also specify some (case-insensitive) common page sizes such as letter and A4. See the epilogue at the bottom for a complete list of the valid sizes. 📐✨

The --fit option scales to fit the image into a rectangle that is either derived from the --imgsize option or otherwise from the --pagesize option. If the --border option is given in addition to the --imgsize option while the --pagesize option is not given, then the page size will be calculated from the image size, respecting the border setting. If the --border option is given in addition to the --pagesize option while the --imgsize option is not given, then the image size will be calculated from the page size, respecting the border setting. If the --border option is given while both the --pagesize and --imgsize options are passed, then the --border option will be ignored. 💀

The --pagesize option or the --imgsize option with the --border option will determine the MediaBox size of the resulting PDF document. 📦

  • -S, --pagesize LxL — Sets the size of the PDF pages. The short-option is the upper case S because it is an mnemonic for being bigger than the image size. 👑
  • -s, --imgsize LxL — Sets the size of the images on the PDF pages. In addition, the unit dpi is allowed which will set the image size as a value of dots per inch. Instead of a unit, width and height values may also have a percentage sign appended, indicating a resize of the image by that percentage. The short-option is the lower case s because it is a mnemonic for being smaller than the page size. 🦋
  • -b, --border L[:L] — Specifies the minimal distance between the image border and the PDF page border. This value Is overwritten by explicit values set by --pagesize or --imgsize. The value will be used when calculating page dimensions from the image dimensions or the other way round. One, or two length values can be given as an argument, separated by a colon. One value specifies the minimal border on all four sides. Two values specify the minimal border on the top/bottom and left/right, respectively. It is not possible to specify asymmetric borders because images will always be centered on the page. symmetric slay 💅
  • -f, --fit FIT — If --imgsize is given, fits the image using these dimensions. Otherwise, fit the image into the dimensions given by --pagesize. FIT is one of into, fill, exact, shrink and enlarge. The default value is "into". See the epilogue at the bottom for a description of the FIT options. 🌸
  • -a, --auto-orient — okay so bestie, if you gave both dimensions of the page via --pagesize, this lowkey conditionally swaps them so the page orientation matches your input image's orientation. And if a page orientation gets flipped, the values you set with --border get flipped too. 💅
  • -r, --rotation, --orientation ROT — tells the tool how to rotate your input images. ROT can be auto, none, ifvalid, 0, 90, 180, or 270. Default is auto, which means rotate according to the EXIF Orientation tag. none and 0 ignore EXIF Orientation values. ifvalid is like auto but ignores invalid EXIF rotation values and just gives a warning instead of throwing an error. (Super useful because many devices like Android phones, Canon cameras, or scanners emit an invalid Orientation tag value of zero. 😭) The values 90, 180, and 270 do a clockwise rotation of the image. 🔄
  • --crop-border L[:L] — sets the border between the CropBox and the MediaBox. You can give one or two length values, separated by a colon. One value = border on all four sides. Two values = border on top/bottom and left/right respectively. No asymmetric borders, bestie. 🚫
  • --bleed-border L[:L] — sets the border between the BleedBox and the MediaBox. One or two length values, separated by a colon. One value = all four sides. Two values = top/bottom and left/right respectively. No asymmetric borders. 🚫
  • --trim-border L[:L] — sets the border between the TrimBox and the MediaBox. One or two length values, separated by a colon. One value = all four sides. Two values = top/bottom and left/right respectively. No asymmetric borders. 🚫
  • --art-border L[:L] — sets the border between the ArtBox and the MediaBox. One or two length values, separated by a colon. One value = all four sides. Two values = top/bottom and left/right respectively. No asymmetric borders. 🚫

✨ Arguments setting metadata ✨

Options handling embedded timestamps, title and author information.

  • --title title — sets the title metadata value. 📝
  • --author author — sets the author metadata value. ✍️
  • --creator creator — sets the creator metadata value. 🎨
  • --producer producer — sets the producer metadata value (default is: img2pdf 0.6.2). 🏭
  • --creationdate creationdate — sets the UTC creation date metadata value in YYYY-MMDD or YYYY-MM-DDTHH:MM or YYYY-MM-DDTHH:MM:SS format, or any format understood by the python dateutil module, or any format understood by date --date. 📅
  • --moddate moddate — sets the UTC modification date metadata value in YYYYMM-DD or YYYY-MM-DDTHH:MM or YYYY-MM-DDTHH:MM:SS format, or any format understood by the python dateutil module, or any format understood by date --date. ⏰
  • --subject subject — sets the subject metadata value. 📋
  • --keywords kw [kw ...] — sets the keywords metadata value (can be given multiple times). 🔑

✨ PDF viewer arguments ✨

PDF files can specify how they are meant to be presented to the user by a PDF viewer.

  • --viewer-panes PANES — instruct the PDF viewer which side panes to show. Valid values are "outlines" and "thumbs". You can't specify both at the same time. 👀
  • --viewer-initial-page NUM — instead of showing the first page, tell the PDF viewer to show the given page instead. Page numbers start with 1. 📄
  • --viewer-magnification MAG — instruct the PDF viewer to open the PDF with a certain zoom level. Valid values are either a floating point number giving the exact zoom level, "fit" (zoom to fit whole page), "fith" (zoom to fit page width), and "fitbh" (zoom to fit visible page width). 🔍
  • --viewer-page-layout LAYOUT — instruct the PDF viewer how to arrange the pages on the screen. Valid values are "single" (display single pages), "onecolumn" (one continuous column), "twocolumnright" (two continuous columns with odd number pages on the right), "twocolumnleft" (two continuous columns with odd numbered pages on the left), "twopageright" (two pages with odd numbered page on the right), and "twopageleft" (two pages with odd numbered page on the left). 📑
  • --viewer-fit-window — instruct the PDF viewer to resize the window to fit the page size. 🪟
  • --viewer-center-window — instruct the PDF viewer to center the PDF viewer window. 🎯
  • --viewer-fullscreen — instruct the PDF viewer to open the PDF in fullscreen mode. 🖥️

✨ Colorspace ✨

Currently, the colorspace must be forced for JPEG 2000 images that are not in the RGB colorspace. Available colorspace options are based on Python Imaging Library (PIL) short handles.

  • RGB — RGB color. 🌈
  • L — Grayscale. 🩶
  • 1 — Black and white (internally converted to grayscale). ⚫⚪
  • CMYK — CMYK color. 🖨️
  • CMYK;I — CMYK color with inversion (for CMYK JPEG files from Adobe). 🔄

✨ Paper sizes ✨

You can specify the short hand paper size names shown in the first column in the table below as arguments to the --pagesize and --imgsize options. The width and height they are mapping to is shown in the second column. Giving the value in the second column has the same effect as giving the short hand in the first column. Appending ^T (a caret/circumflex followed by the letter T) turns the paper size from portrait into landscape. The postfix thus symbolizes the transpose.

Note that on Windows cmd.exe the caret symbol is the escape character, so you need to put quotes around the option value.

The values are case insensitive.

  • A0 — 841mmx1189mm
  • A1 — 594mmx841mm
  • A2 — 420mmx594mm
  • A3 — 297mmx420mm
  • A4 — 210mmx297mm
  • A5 — 148mmx210mm
  • A6 — 105mmx148mm
  • B0 — 1000mmx1414mm
  • B1 — 707mmx1000mm
  • B2 — 500mmx707mm
  • B3 — 353mmx500mm
  • B4 — 250mmx353mm
  • B5 — 176mmx250mm
  • B6 — 125mmx176mm
  • JB0 — 1030mmx1456mm
  • JB1 — 728mmx1030mm
  • JB2 — 515mmx728mm
  • JB3 — 364mmx515mm
  • JB4 — 257mmx364mm
  • JB5 — 182mmx257mm
  • JB6 — 128mmx182mm
  • Legal — 8.5inx14in
  • Letter — 8.5inx11in
  • Tabloid — 11inx17in

✨ Fit options ✨

The img2pdf options for the --fit argument are shown in the first column in the table below. The function of these options can be mapped to the geometry operators of imagemagick. For users who are familiar with imagemagick, the corresponding operator is shown in the second column. The third column shows whether or not the aspect ratio is preserved for that option (same as in imagemagick). Just like imagemagick, img2pdf tries hard to preserve the aspect ratio, so if the --fit argument is not given, then the default is "into" which corresponds to the absence of any operator in imagemagick. The value of the --fit option is case insensitive.

  • into — operator: (none), aspect ratio preserved: Y — The default. Width and height values specify maximum values. 📏
  • fill — operator: ^, aspect ratio preserved: Y — Width and height values specify the minimum values. 📐
  • exact — operator: !, aspect ratio preserved: N — Width and height emphatically given. 🎯
  • shrink — operator: >, aspect ratio preserved: Y — Shrinks an image with dimensions larger than the given ones (and otherwise behaves like "into"). 🔽
  • enlarge — operator: <, aspect ratio preserved: Y — Enlarges an image with dimensions smaller than the given ones (and otherwise behaves like "into"). 🔼

✨ Argument parsing ✨

Argument long options can be abbreviated to a prefix if the abbreviation is unambiguous. That is, the prefix must match a unique option. 🔤

Beware of your shell interpreting argument values as special characters (like the semicolon in the CMYK;I colorspace option). If in doubt, put the argument values in single quotes. 🐚

If you want an argument value to start with one or more minus characters, you must use the long option name and join them with an equal sign like so:

$ img2pdf --author=--test--

If your input file name starts with one or more minus characters, either separate the input files from the other arguments by two minus signs:

$ img2pdf -- --my-file-starts-with-two-minuses.jpg

Or be more explicit about its relative path by prepending a ./:

$ img2pdf ./--my-file-starts-with-two-minuses.jpg

The order of non-positional arguments (all arguments other than the input images) does not matter. 🔀

✨ EXAMPLES ✨

okay bestie, so like — lines that start with a dollar sign are the commands you actually type into your terminal, mwah 💅 that $ is literally just your command prompt being cute, it is not part of the command, do not type it, I'm begging 🙈

Convert two scans in JPEG format to a PDF document. 🎀

$ img2pdf --output out.pdf page1.jpg page2.jpg

Use a custom dpi value for the input images:

$ img2pdf --output out.pdf --imgsize 300dpi page1.jpg page2.jpg

Convert a directory of JPEG images into a PDF with printable A4 pages in landscape mode. 🦋 On each page, the photo takes the maximum amount of space while preserving its aspect ratio, plus a print border of 2 cm on the top and bottom and 2.5 cm on the left and right hand side. the way that it just fits? iconic.

$ img2pdf --output out.pdf --pagesize "A4^T" --border 2cm:2.5cm *.jpg

On each A4 page, fit images into a 10 cm times 15 cm rectangle but keep the original image size if the image is smaller than that.

$ img2pdf --output out.pdf -S A4 --imgsize 10cmx15cm --fit shrink *.jpg

Prepare a directory of photos to be printed borderless on photo paper with a 3:2 aspect ratio and rotate each page so that its orientation is the same as the input image. main character energy fr fr 🔥

$ img2pdf --output out.pdf --pagesize 15cmx10cm --auto-orient *.jpg

Encode a grayscale JPEG2000 image. ⭐ Heads up bestie: the colorspace has to be forced here, because img2pdf cannot read it from the JPEG2000 file automatically. no cap.

$ img2pdf --output out.pdf --colorspace L input.jp2

👑 AUTHOR

Written by Johannes Schauer Marin Rodrigues <josch@mister-muffin.de> — absolute legend, we stan 💜

💌 REPORTING BUGS

Found something cursed? Report bugs at https://gitlab.mister-muffin.de/josch/img2pdf/issues 🐛✨

and that's the whole page bestie!! 🌸 this one's from img2pdf 0.6.2, dated November 2025, and it's the IMG2PDF(1) manual — go forth and make PDFs, you gorgeous genius 🫶💖🎀

📦 where this page comes from