{"id":3517,"library":"img2pdf","title":"img2pdf: Lossless Image to PDF Conversion","description":"img2pdf is a Python library designed for lossless conversion of raster images to PDF. It excels at embedding JPEG and JPEG2000 files without re-encoding, preserving original quality and minimizing file size, treating PDF primarily as a container format. For other image formats, it uses lossless zip compression. The current version is 0.6.3, and the library maintains an active release cadence with regular updates.","status":"active","version":"0.6.3","language":"python","source_language":"en","source_url":"https://github.com/josch/img2pdf","tags":["image","pdf","conversion","lossless","jpeg","png","tiff","document generation"],"install":[{"cmd":"pip install img2pdf","lang":"bash","label":"Install img2pdf"}],"dependencies":[{"reason":"Used by img2pdf to obtain image metadata and convert input images if necessary (e.g., non-JPEG/JPEG2000 formats).","package":"Pillow","optional":false},{"reason":"Can be used as an alternative rendering engine (supported since 0.4.0).","package":"pikepdf","optional":true}],"imports":[{"symbol":"img2pdf","correct":"import img2pdf"}],"quickstart":{"code":"import img2pdf\nimport os\n\n# Create a dummy image file for demonstration\ndummy_image_data = bytes([0xFF, 0xD8, 0xFF, 0xE0, 0x00, 0x10, 0x4A, 0x46, 0x49, 0x46, 0x00, 0x01, 0x01, 0x00, 0x00, 0x01, 0x00, 0x01, 0x00, 0x00, 0xFF, 0xDB, 0x00, 0x43, 0x00, 0x03, 0x02, 0x02, 0x02, 0x02, 0x02, 0x03, 0x02, 0x02, 0x02, 0x03, 0x03, 0x03, 0x03, 0x04, 0x06, 0x04, 0x04, 0x04, 0x04, 0x04, 0x08, 0x06, 0x06, 0x05, 0x06, 0x09, 0x08, 0x0A, 0x0A, 0x09, 0x08, 0x09, 0x09, 0x0A, 0x0C, 0x0F, 0x0C, 0x0A, 0x0B, 0x0E, 0x0B, 0x09, 0x09, 0x0D, 0x11, 0x0D, 0x0E, 0x0F, 0x10, 0x10, 0x11, 0x10, 0x0A, 0x0C, 0x12, 0x13, 0x12, 0x10, 0x13, 0x11, 0x11, 0x10, 0xFF, 0xC0, 0x00, 0x11, 0x08, 0x00, 0x01, 0x00, 0x01, 0x03, 0x01, 0x22, 0x00, 0x02, 0x11, 0x01, 0x03, 0x11, 0x01, 0xFF, 0xC4, 0x00, 0x1F, 0x00, 0x00, 0x01, 0x05, 0x01, 0x01, 0x01, 0x01, 0x01, 0x01, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x01, 0x02, 0x03, 0x04, 0x05, 0x06, 0x07, 0x08, 0x09, 0x0A, 0x0B, 0xFF, 0xC4, 0x00, 0x1F, 0x01, 0x00, 0x03, 0x01, 0x01, 0x01, 0x01, 0x01, 0x01, 0x01, 0x01, 0x01, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x01, 0x02, 0x03, 0x04, 0x05, 0x06, 0x07, 0x08, 0x09, 0x0A, 0x0B, 0xFF, 0xC4, 0x00, 0x1F, 0x10, 0x00, 0x01, 0x03, 0x01, 0x01, 0x01, 0x01, 0x01, 0x01, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x01, 0x02, 0x03, 0x04, 0x05, 0x06, 0x07, 0x08, 0x09, 0x0A, 0x0B, 0xFF, 0xC4, 0x00, 0x1F, 0x11, 0x00, 0x03, 0x01, 0x01, 0x01, 0x01, 0x01, 0x01, 0x01, 0x01, 0x01, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x01, 0x02, 0x03, 0x04, 0x05, 0x06, 0x07, 0x08, 0x09, 0x0A, 0x0B, 0xFF, 0xDA, 0x00, 0x0C, 0x03, 0x01, 0x00, 0x02, 0x11, 0x03, 0x11, 0x00, 0x3F, 0x00, 0xF2, 0xCA, 0x88, 0x64, 0x02, 0xFF, 0xD9])\nwith open('temp_image.jpg', 'wb') as f:\n    f.write(dummy_image_data)\n\n# --- Quickstart --- \n\n# Convert a single image file to PDF\nwith open('output_single.pdf', 'wb') as f_pdf:\n    f_pdf.write(img2pdf.convert('temp_image.jpg'))\nprint('Successfully converted single image to output_single.pdf')\n\n# Convert multiple images to a multi-page PDF\n# (for demonstration, we'll just use the same dummy image twice)\nimage_files = ['temp_image.jpg', 'temp_image.jpg']\nwith open('output_multiple.pdf', 'wb') as f_pdf:\n    f_pdf.write(img2pdf.convert(image_files))\nprint('Successfully converted multiple images to output_multiple.pdf')\n\n# Clean up dummy image\nos.remove('temp_image.jpg')\n","lang":"python","description":"This quickstart demonstrates how to convert a single image or a list of image file paths into PDF documents. The `img2pdf.convert()` function handles the conversion, and the result is written to a binary file handle."},"warnings":[{"fix":"Disable the safeguard by passing `--pillow-limit-break` option in CLI or `rotation=img2pdf.Rotation.ifvalid` in library usage, if you understand the risks.","message":"Pillow's decompression bomb limit can prevent processing of very large images. img2pdf uses Pillow for metadata and conversion of non-JPEG/JPEG2000 images.","severity":"gotcha","affected_versions":"All versions using Pillow"},{"fix":"Fix input images with `exiftool` or similar software, or run img2pdf with `--rotation=ifvalid` (CLI) or pass `rotation=img2pdf.Rotation.ifvalid` to `convert()` (library).","message":"JPEG images with an invalid EXIF Orientation value of zero (often from Android phones or Canon DSLR cameras) can cause errors.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Sort the list of image file paths (e.g., using `sorted()`) before passing them to `img2pdf.convert()`.","message":"When converting multiple images from a directory, `os.listdir()` or `os.scandir()` return files in arbitrary order, which can lead to incorrect page sequencing in the final PDF. Ensure images are explicitly sorted before passing to `img2pdf.convert()`.","severity":"gotcha","affected_versions":"All versions"},{"fix":"If a TIFF file uses unsupported compression, convert it to a different format (like uncompressed TIFF or JPEG) before passing it to img2pdf.","message":"Certain TIFF compression methods, especially 'Old-Style JPEG (in tiff)', might not be supported, leading to conversion failures.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Ensure the command is structured as `img2pdf -o output.pdf input1.jpg input2.png`.","wrong":"img2pdf input1.jpg input2.png -o output.pdf","message":"In the command-line usage, the output file argument (`-o`) must generally precede the input image files. Incorrect order can lead to unexpected behavior or errors.","severity":"gotcha","affected_versions":"CLI usage"}],"env_vars":null,"search_vec":"'0.6.3':60 'activ':66 'cadenc':68 'compress':55 'contain':45 'convers':6,15,74 'current':57 'design':12 'document':79 'embed':24 'encod':32 'excel':22 'file':28,38 'format':46,50 'generat':80 'imag':3,18,49,72 'img2pdf':1,7 'jpeg':25,76 'jpeg2000':27 'librari':11,63 'lossless':2,14,53,75 'maintain':64 'minim':37 'origin':34 'pdf':5,20,41,73 'png':77 'preserv':33 'primarili':42 'python':10 'qualiti':35 'raster':17 're':31 're-encod':30 'regular':70 'releas':67 'size':39 'tiff':78 'treat':40 'updat':71 'use':52 'version':58 'without':29 'zip':54","created_at":"2026-04-11T17:33:00.191021+00:00","updated_at":"2026-04-16T15:42:35.983874+00:00","problems":[{"fix":"Ensure the file path provided to `img2pdf.convert()` is correct and accessible. If intending to pass raw image data, provide it as a `bytes` object, not a string.","cause":"This error occurs when `img2pdf.convert()` is passed a string that it fails to open as a file (e.g., file not found, permissions), causing it to incorrectly attempt to interpret the string as raw image data, which must be a bytes object.","error":"TypeError: a bytes-like object is required, not 'str'"},{"fix":"Install the library using `pip install img2pdf` (or `pip3 install img2pdf`). Verify that the Python interpreter running the script is the same one where the package was installed.","cause":"The `img2pdf` package is not installed in the Python environment currently being used, or there is a conflict/misconfiguration with multiple Python installations or their respective package paths.","error":"ModuleNotFoundError: No module named 'img2pdf'"},{"fix":"Provide the full, absolute path to the image file(s). Use `os.path.join()` or `pathlib.Path` to construct correct and platform-independent file paths.","cause":"The `img2pdf` library or the underlying file system operation cannot locate the specified image file. This frequently happens when providing only filenames from `os.listdir()` without their full directory path, or if the path is simply incorrect.","error":"IOError: [Errno 2] No such file or directory: '...' (or FileNotFoundError)"},{"fix":"Verify the image file is not corrupt and is in a standard, widely supported format (e.g., common JPEG, PNG, or TIFF types). For problematic TIFFs or other complex formats, consider pre-converting them to a simpler format like JPEG or PNG using another tool before feeding them to `img2pdf`. If the issue is related to EXIF orientation, try passing `rotation=img2pdf.Rotation.ifvalid` to the `convert` function.","cause":"These errors indicate that the Pillow library, which `img2pdf` uses for image processing, cannot properly read, identify, or process the input image. This can be due to an unsupported image format, a corrupt file, or specific encoding/compression methods (e.g., 'Old-Style JPEG (in tiff)' compression for TIFF files) that are not natively supported by Pillow or `img2pdf`.","error":"ValueError: unknown colorspace (or PIL: error reading image: cannot identify)"}],"ecosystem":"pypi","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":"0.6.3","cli_name":"img2pdf","cli_version":"img2pdf 0.6.3","type":"library","homepage":"https://gitlab.mister-muffin.de/josch/img2pdf","github":null,"docs":null,"changelog":null,"pypi":"https://pypi.org/project/img2pdf/","npm":null,"openapi_spec":null,"status_page":null,"smithery":null,"categories":["serialization","data"],"base_url":null,"auth_type":null,"provenance":{"verified_status":"passing","verified_at":"2026-06-28","last_verified":"2026-08-29","next_check":"2026-07-28","install_tag":null}}