Save pictures to PDF documents from the command line and from your Python programs.
Installation
pip install pictureshowUsage
As a command line tool
usage: pictureshow [options] PICTURE [PICTURE ...] -o PATH
positional arguments:
PICTURE one or more input file paths
options:
-h, --help show this help message and exit
-V, --version show program's version number and exit
-q, --quiet do not print output to stdout
-v, --verbose show details of input files skipped due to error
-F, --fail MODE control the exit code: 'skipped' exits with code 2 if
at least one input file was skipped due to an error;
'no-output' (default) exits with code 2 if all files
were skipped and no PDF file was saved; 'no' exits
with code 0 even if all files were skipped
output file options:
-o, --output-file PATH
path of the output PDF file (required)
-f, --force-overwrite
save to output file path even if file exists
page properties options:
-p, --page-size SIZE specify page size; default is A4 (available sizes: A0,
A1, A2, A3, A4, A5, A6, A7, A8, A9, A10, B0, B1, B2,
B3, B4, B5, B6, B7, B8, B9, B10, C0, C1, C2, C3, C4,
C5, C6, C7, C8, C9, C10, LETTER, LEGAL,
ELEVENSEVENTEEN, JUNIOR_LEGAL, HALF_LETTER,
GOV_LETTER, GOV_LEGAL, TABLOID, LEDGER)
-L, --landscape set landscape orientation of pages
-b, --bg-color COLOR specify page background color as 6-digit hexadecimal
RGB, e.g. ff8c00
picture layout options:
-l, --layout LAYOUT specify grid layout (columns x rows) of pictures on
page, e.g. 2x3 or 2,3; default is 1x1
-m, --margin MARGIN set width of empty space around the cells containing
pictures; default is 72 (72 points = 1 inch)
-s, --stretch-small scale small pictures up to fit cells
-c, --fill-cell fill cells with pictures, ignoring the pictures'
aspect ratioExamples
Save single picture to PDF:
$ pictureshow pics/potato.jpg -o potato.pdf
.
Saved 1 picture (1 page) to 'potato.pdf'Save multiple pictures, four pictures per page (two columns, two rows), set page orientation to landscape:
$ pictureshow -l 2x2 -L vegetables/* -o vegetables
..................................................
Saved 50 pictures (13 pages) to 'vegetables.pdf'(Please note that if the output filename has no extension specified, .pdf will be appended to it. This only applies for the command line tool.)
You can also save pictures from URLs:
$ pictureshow https://httpbin.org/image/jpeg https://httpbin.org/image/png -o pics
..
Saved 2 pictures (2 pages) to 'pics.pdf'But please note that this feature is not tested and depends solely on the underlying reportlab backend.
As a Python library
Using the PictureShow class
Example:
from pictureshow import PictureShow
pictures = PictureShow(
'pics/cucumber.jpg',
'pics/onion.jpg',
)
pictures.save_pdf('vegetables.pdf')The customization parameters of the save_pdf method are keyword-only and their default values correspond to the above shown command line options:
PictureShow.save_pdf(
output_file,
*,
force_overwrite=False,
page_size='A4',
landscape=False,
bg_color=None,
layout=(1, 1),
margin=72,
stretch_small=False,
fill_cell=False,
)Using the pictures_to_pdf shortcut function
Example:
from pictureshow import pictures_to_pdf
pictures_to_pdf(
'pics/cucumber.jpg',
'pics/onion.jpg',
output_file='vegetables.pdf',
)The customization parameters of the pictures_to_pdf function are keyword-only and their default values correspond to the above shown command line options:
pictures_to_pdf(
*pic_files,
output_file,
force_overwrite=False,
page_size='A4',
landscape=False,
bg_color=None,
layout=(1, 1),
margin=72,
stretch_small=False,
fill_cell=False,
)1 maintainer
Metadata
1 maintainer
Release files for pictureshow 0.14.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| pictureshow-0.14.0.tar.gz | 8.4 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| pictureshow-0.14.0-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 18.9 kB
Release files / pictureshow-0.14.0.tar.gz
| Download URL | pictureshow-0.14.0.tar.gz |
|---|---|
| Size | 8.4 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
b2e493c1ab186fef58c68aee2604dee652ee0a5089c21d0704c1a1adb8b5886a
|
|
BLAKE2b-256 checksum How to use checksums |
39e30ec8a743c07483f84b2eee8b01b663eeb1871cbf7c61577c8c0afef36870
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.7
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 16, 2025.
Transparency logRelease files / pictureshow-0.14.0-py3-none-any.whl
| Download URL | pictureshow-0.14.0-py3-none-any.whl |
|---|---|
| Size | 10.6 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
b4e744b4d1f12a4a7abd1c1d17043bd78d5783f3c1df04c0308906beb7d12746
|
|
BLAKE2b-256 checksum How to use checksums |
043d6a20a330fd2f32064ebfc453fa047bc95afb20df2bc0fadafe1617642bd4
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.7
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 16, 2025.
Transparency log
