fotolab

A console program to manipulate photos.

Installation

Stable version From PyPI using uv:

uv tool install fotolab

Upgrade to latest stable version:

uv tool upgrade fotolab

Optional extra for faster black-bar detection in the crop subcommand (falls back to pixel sampling without it):

uv tool install "fotolab[numpy]"

Optional extra with OpenCV, required by the face subcommand to detect faces:

uv tool install "fotolab[face]"

Usage

fotolab -h

usage: fotolab [-h] [-o] [-q] [-d] [-V] [--dry-run]
               {animate,auto,border,bw,contrast,crop,env,face,halftone,info,montage,resize,rotate,sharpen,watermark} ...

A console program to manipulate photos.

website: https://github.com/kianmeng/fotolab
changelog: https://github.com/kianmeng/fotolab/blob/master/CHANGELOG.md
issues: https://github.com/kianmeng/fotolab/issues

positional arguments:
  {animate,auto,border,bw,contrast,crop,env,face,halftone,info,montage,resize,rotate,sharpen,watermark}
                    sub-command help
    animate         animate an image
    auto            auto adjust (resize, contrast, and watermark) a photo
    border          add border to image
    bw              apply a black and white filter effect to an image
    contrast        contrast an image.
    crop            crop an image
    env             print environment information for bug reporting
    face            mosaic or blur the faces in an image
    halftone        halftone an image
    info            info an image
    montage         montage a list of image
    resize          resize an image
    rotate          rotate an image
    sharpen         sharpen an image
    watermark       watermark an image

options:
  -h, --help        show this help message and exit
  -o, --overwrite   overwrite existing image
  -q, --quiet       suppress all logging
  -d, --debug       show debugging log and stacktrace
  -V, --version     show program's version number and exit
  --dry-run         print the output filenames without writing any files

fotolab animate

fotolab animate -h

usage: fotolab animate [-h] [-o] [-q] [--debug] [--dry-run] [-op]
                       [-od OUTPUT_DIR] [-of OUTPUT_FILENAME] [-j JOBS]
                       [-f FORMAT] [-d DURATION] [-l LOOP]
                       [--webp-quality QUALITY] [--webp-lossless]
                       [--webp-method METHOD]
                       IMAGE_PATHS [IMAGE_PATHS ...]

positional arguments:
  IMAGE_PATHS           set the image filenames

options:
  -h, --help            show this help message and exit
  -o, --overwrite       overwrite existing image
  -q, --quiet           suppress all logging
  --debug               show debugging log and stacktrace
  --dry-run             print the output filenames without writing any files
  -op, --open           open the image using default program (default:
                        'False')
  -od, --output-dir OUTPUT_DIR
                        set default output folder (default: 'output')
  -of, --output-filename OUTPUT_FILENAME
                        set output filename (default: 'None')
  -j, --jobs JOBS       process images in parallel using the given number of
                        worker processes (default: '1')
  -f, --format FORMAT   set the image format (default: 'gif')
  -d, --duration DURATION
                        set the duration in milliseconds (must be a positive
                        integer, default: '2500')
  -l, --loop LOOP       set the loop cycle (default: '0')
  --webp-quality QUALITY
                        set WEBP quality (0-100, default: '80')
  --webp-lossless       enable WEBP lossless compression (default: 'False')
  --webp-method METHOD  set WEBP encoding method (0=fast, 6=slow/best,
                        default: '4')

fotolab auto

fotolab auto -h

usage: fotolab auto [-h] [-o] [-q] [--debug] [--dry-run] [-op]
                    [-od OUTPUT_DIR] [-of OUTPUT_FILENAME] [-j JOBS]
                    [-t TITLE] [-w WATERMARK_TEXT]
                    IMAGE_PATHS [IMAGE_PATHS ...]

positional arguments:
  IMAGE_PATHS           set the image filenames

options:
  -h, --help            show this help message and exit
  -o, --overwrite       overwrite existing image
  -q, --quiet           suppress all logging
  --debug               show debugging log and stacktrace
  --dry-run             print the output filenames without writing any files
  -op, --open           open the image using default program (default:
                        'False')
  -od, --output-dir OUTPUT_DIR
                        set default output folder (default: 'output')
  -of, --output-filename OUTPUT_FILENAME
                        set output filename (default: 'None')
  -j, --jobs JOBS       process images in parallel using the given number of
                        worker processes (default: '1')
  -t, --title TITLE     set the title (default: 'None')
  -w, --watermark WATERMARK_TEXT
                        set the watermark (default: 'kianmeng.org')

fotolab border

fotolab border -h

usage: fotolab border [-h] [-o] [-q] [--debug] [--dry-run] [-op]
                      [-od OUTPUT_DIR] [-of OUTPUT_FILENAME] [-j JOBS]
                      [-c COLOR] [-w WIDTH] [-wt WIDTH] [-wr WIDTH]
                      [-wb WIDTH] [-wl WIDTH]
                      IMAGE_PATHS [IMAGE_PATHS ...]

positional arguments:
  IMAGE_PATHS           set the image filenames

options:
  -h, --help            show this help message and exit
  -o, --overwrite       overwrite existing image
  -q, --quiet           suppress all logging
  --debug               show debugging log and stacktrace
  --dry-run             print the output filenames without writing any files
  -op, --open           open the image using default program (default:
                        'False')
  -od, --output-dir OUTPUT_DIR
                        set default output folder (default: 'output')
  -of, --output-filename OUTPUT_FILENAME
                        set output filename (default: 'None')
  -j, --jobs JOBS       process images in parallel using the given number of
                        worker processes (default: '1')
  -c, --color COLOR     set the color of border (default: 'black')
  -w, --width WIDTH     set the width of border in pixels (default: '10')
  -wt, --width-top WIDTH
                        set the width of top border in pixels (default: '0')
  -wr, --width-right WIDTH
                        set the width of right border in pixels (default: '0')
  -wb, --width-bottom WIDTH
                        set the width of bottom border in pixels (default:
                        '0')
  -wl, --width-left WIDTH
                        set the width of left border in pixels (default: '0')

fotolab bw

fotolab bw -h

usage: fotolab bw [-h] [-o] [-q] [--debug] [--dry-run] [-op] [-od OUTPUT_DIR]
                  [-of OUTPUT_FILENAME] [-j JOBS] [-f FILTER_TYPE |
                  --all-filters] [--contrast CONTRAST]
                  [--brightness BRIGHTNESS] [--sharpen SHARPEN]
                  IMAGE_PATHS [IMAGE_PATHS ...]

positional arguments:
  IMAGE_PATHS           set the image filenames

options:
  -h, --help            show this help message and exit
  -o, --overwrite       overwrite existing image
  -q, --quiet           suppress all logging
  --debug               show debugging log and stacktrace
  --dry-run             print the output filenames without writing any files
  -op, --open           open the image using default program (default:
                        'False')
  -od, --output-dir OUTPUT_DIR
                        set default output folder (default: 'output')
  -of, --output-filename OUTPUT_FILENAME
                        set output filename (default: 'None')
  -j, --jobs JOBS       process images in parallel using the given number of
                        worker processes (default: '1')
  -f, --filter FILTER_TYPE
                        specify the black and white filter type to apply,
                        choices: DEEP_BLACK, TRUE_GRAY, SOFT_LIGHT, GRAIN
  --all-filters         apply all available filters to the image
  --contrast CONTRAST   apply a custom contrast factor (e.g., 1.5 for 50%
                        increase)
  --brightness BRIGHTNESS
                        apply a custom brightness factor (e.g., 1.1 for 10%
                        increase)
  --sharpen SHARPEN     apply a custom sharpen factor (e.g., 2.0 for double
                        sharpening)

fotolab contrast

fotolab contrast -h

usage: fotolab contrast [-h] [-o] [-q] [--debug] [--dry-run] [-op]
                        [-od OUTPUT_DIR] [-of OUTPUT_FILENAME] [-j JOBS]
                        [-c CUTOFF]
                        IMAGE_PATHS [IMAGE_PATHS ...]

positional arguments:
  IMAGE_PATHS           set the image filenames

options:
  -h, --help            show this help message and exit
  -o, --overwrite       overwrite existing image
  -q, --quiet           suppress all logging
  --debug               show debugging log and stacktrace
  --dry-run             print the output filenames without writing any files
  -op, --open           open the image using default program (default:
                        'False')
  -od, --output-dir OUTPUT_DIR
                        set default output folder (default: 'output')
  -of, --output-filename OUTPUT_FILENAME
                        set output filename (default: 'None')
  -j, --jobs JOBS       process images in parallel using the given number of
                        worker processes (default: '1')
  -c, --cutoff CUTOFF   set the percentage (0-50) of lightest or darkest
                        pixels to discard from histogram (default: '1.0')

fotolab crop

fotolab crop -h

usage: fotolab crop [-h] [-o] [-q] [--debug] [--dry-run] [-op]
                    [-od OUTPUT_DIR] [-of OUTPUT_FILENAME] [-j JOBS] (-b BOX |
                    --auto-crop) [-t THRESHOLD]
                    IMAGE_PATHS [IMAGE_PATHS ...]

positional arguments:
  IMAGE_PATHS           set the image filenames

options:
  -h, --help            show this help message and exit
  -o, --overwrite       overwrite existing image
  -q, --quiet           suppress all logging
  --debug               show debugging log and stacktrace
  --dry-run             print the output filenames without writing any files
  -op, --open           open the image using default program (default:
                        'False')
  -od, --output-dir OUTPUT_DIR
                        set default output folder (default: 'output')
  -of, --output-filename OUTPUT_FILENAME
                        set output filename (default: 'None')
  -j, --jobs JOBS       process images in parallel using the given number of
                        worker processes (default: '1')
  -b, --box BOX         set the crop area as a 4-tuple (left, upper, right,
                        lower), e.g., '100,100,500,500'
  --auto-crop           automatically detect and crop black bars from all
                        sides
  -t, --threshold THRESHOLD
                        brightness threshold to detect black bars (0-255,
                        default: 5)

fotolab halftone

fotolab halftone -h

usage: fotolab halftone [-h] [-o] [-q] [--debug] [--dry-run] [-op]
                        [-od OUTPUT_DIR] [-of OUTPUT_FILENAME] [-j JOBS] [-ba]
                        [-c CELLS] [-g]
                        IMAGE_PATHS [IMAGE_PATHS ...]

positional arguments:
  IMAGE_PATHS           set the image filenames

options:
  -h, --help            show this help message and exit
  -o, --overwrite       overwrite existing image
  -q, --quiet           suppress all logging
  --debug               show debugging log and stacktrace
  --dry-run             print the output filenames without writing any files
  -op, --open           open the image using default program (default:
                        'False')
  -od, --output-dir OUTPUT_DIR
                        set default output folder (default: 'output')
  -of, --output-filename OUTPUT_FILENAME
                        set output filename (default: 'None')
  -j, --jobs JOBS       process images in parallel using the given number of
                        worker processes (default: '1')
  -ba, --before-after   generate a GIF showing before and after changes
  -c, --cells CELLS     set number of cells across the image width (default:
                        50)
  -g, --grayscale       convert image to grayscale before applying halftone

fotolab info

fotolab info -h

usage: fotolab info [-h] [-o] [-q] [--debug] [--dry-run] [-s] [--camera]
                    [--datetime]
                    IMAGE_FILENAME

positional arguments:
  IMAGE_FILENAME   set the image filename

options:
  -h, --help       show this help message and exit
  -o, --overwrite  overwrite existing image
  -q, --quiet      suppress all logging
  --debug          show debugging log and stacktrace
  --dry-run        print the output filenames without writing any files
  -s, --sort       show image info by sorted field name
  --camera         show the camera maker details
  --datetime       show the datetime

fotolab rotate

fotolab rotate -h

usage: fotolab rotate [-h] [-o] [-q] [--debug] [--dry-run] [-op]
                      [-od OUTPUT_DIR] [-of OUTPUT_FILENAME] [-j JOBS]
                      [-r ROTATION] [-cw]
                      IMAGE_PATHS [IMAGE_PATHS ...]

positional arguments:
  IMAGE_PATHS           set the image filenames

options:
  -h, --help            show this help message and exit
  -o, --overwrite       overwrite existing image
  -q, --quiet           suppress all logging
  --debug               show debugging log and stacktrace
  --dry-run             print the output filenames without writing any files
  -op, --open           open the image using default program (default:
                        'False')
  -od, --output-dir OUTPUT_DIR
                        set default output folder (default: 'output')
  -of, --output-filename OUTPUT_FILENAME
                        set output filename (default: 'None')
  -j, --jobs JOBS       process images in parallel using the given number of
                        worker processes (default: '1')
  -r, --rotation ROTATION
                        Rotation angle in degrees (default: '0')
  -cw, --clockwise      Rotate clockwise (default: 'False')

fotolab montage

fotolab montage -h

usage: fotolab montage [-h] [-o] [-q] [--debug] [--dry-run] [-op]
                       [-od OUTPUT_DIR] [-of OUTPUT_FILENAME] [-j JOBS]
                       [-b BORDER] [-bc COLOR]
                       IMAGE_PATHS [IMAGE_PATHS ...]

positional arguments:
  IMAGE_PATHS           set the image filenames

options:
  -h, --help            show this help message and exit
  -o, --overwrite       overwrite existing image
  -q, --quiet           suppress all logging
  --debug               show debugging log and stacktrace
  --dry-run             print the output filenames without writing any files
  -op, --open           open the image using default program (default:
                        'False')
  -od, --output-dir OUTPUT_DIR
                        set default output folder (default: 'output')
  -of, --output-filename OUTPUT_FILENAME
                        set output filename (default: 'None')
  -j, --jobs JOBS       process images in parallel using the given number of
                        worker processes (default: '1')
  -b, --border BORDER   set the border width for each image (default: '0')
  -bc, --border-color COLOR
                        set the border color for each image (default: 'black')

fotolab resize

fotolab resize -h

usage: fotolab resize [-h] [-o] [-q] [--debug] [--dry-run] [-op]
                      [-od OUTPUT_DIR] [-of OUTPUT_FILENAME] [-j JOBS] [-c]
                      [-l CANVAS_COLOR] [-W WIDTH] [-H HEIGHT]
                      [-ar ASPECT_RATIO]
                      IMAGE_PATHS [IMAGE_PATHS ...]

positional arguments:
  IMAGE_PATHS           set the image filenames

options:
  -h, --help            show this help message and exit
  -o, --overwrite       overwrite existing image
  -q, --quiet           suppress all logging
  --debug               show debugging log and stacktrace
  --dry-run             print the output filenames without writing any files
  -op, --open           open the image using default program (default:
                        'False')
  -od, --output-dir OUTPUT_DIR
                        set default output folder (default: 'output')
  -of, --output-filename OUTPUT_FILENAME
                        set output filename (default: 'None')
  -j, --jobs JOBS       process images in parallel using the given number of
                        worker processes (default: '1')
  -c, --canvas          paste image onto a larger canvas
  -l, --canvas-color CANVAS_COLOR
                        the color of the extended larger canvas(default:
                        'black')
  -W, --width WIDTH     set the width of the image
  -H, --height HEIGHT   set the height of the image
  -ar, --aspect-ratio ASPECT_RATIO
                        set the aspect ratio of the image (e.g., '16:9',
                        '4:3')

fotolab sharpen

fotolab sharpen -h

usage: fotolab sharpen [-h] [-o] [-q] [--debug] [--dry-run] [-op]
                       [-od OUTPUT_DIR] [-of OUTPUT_FILENAME] [-j JOBS]
                       [-r RADIUS] [-p PERCENT] [-t THRESHOLD] [-ba]
                       IMAGE_PATHS [IMAGE_PATHS ...]

positional arguments:
  IMAGE_PATHS           set the image filenames

options:
  -h, --help            show this help message and exit
  -o, --overwrite       overwrite existing image
  -q, --quiet           suppress all logging
  --debug               show debugging log and stacktrace
  --dry-run             print the output filenames without writing any files
  -op, --open           open the image using default program (default:
                        'False')
  -od, --output-dir OUTPUT_DIR
                        set default output folder (default: 'output')
  -of, --output-filename OUTPUT_FILENAME
                        set output filename (default: 'None')
  -j, --jobs JOBS       process images in parallel using the given number of
                        worker processes (default: '1')
  -r, --radius RADIUS   set the radius or size of edges (default: '1')
  -p, --percent PERCENT
                        set the amount of overall strength of sharpening
                        effect (default: '100')
  -t, --threshold THRESHOLD
                        set the minimum brightness changed to be sharpened
                        (default: '3')
  -ba, --before-after   generate a GIF showing before and after changes

fotolab watermark

fotolab watermark -h

usage: fotolab watermark [-h] [-o] [-q] [--debug] [--dry-run] [-op]
                         [-od OUTPUT_DIR] [-of OUTPUT_FILENAME] [-j JOBS]
                         [-t WATERMARK_TEXT]
                         [-p {top-left,top-center,top-right,left-center,center,right-center,bottom-left,bottom-center,bottom-right}]
                         [-pd PADDING] [--padding-x PADDING_X]
                         [--padding-y PADDING_Y] [-fs FONT_SIZE]
                         [-fc FONT_COLOR] [-ow OUTLINE_WIDTH]
                         [-oc OUTLINE_COLOR] [-a ALPHA_VALUE] [--camera]
                         [-l | --lowercase | --no-lowercase]
                         IMAGE_PATHS [IMAGE_PATHS ...]

positional arguments:
  IMAGE_PATHS           set the image filenames

options:
  -h, --help            show this help message and exit
  -o, --overwrite       overwrite existing image
  -q, --quiet           suppress all logging
  --debug               show debugging log and stacktrace
  --dry-run             print the output filenames without writing any files
  -op, --open           open the image using default program (default:
                        'False')
  -od, --output-dir OUTPUT_DIR
                        set default output folder (default: 'output')
  -of, --output-filename OUTPUT_FILENAME
                        set output filename (default: 'None')
  -j, --jobs JOBS       process images in parallel using the given number of
                        worker processes (default: '1')
  -t, --text WATERMARK_TEXT
                        set the watermark text (default: 'kianmeng.org')
  -p, --position {top-left,top-center,top-right,left-center,center,right-center,bottom-left,bottom-center,bottom-right}
                        set position of the watermark text (default: 'bottom-
                        left')
  -pd, --padding PADDING
                        set the padding of the watermark text relative to the
                        image (default: '15')
  --padding-x PADDING_X
                        set the horizontal padding of the watermark text
                        relative to the image (overrides --padding for x-axis)
  --padding-y PADDING_Y
                        set the vertical padding of the watermark text
                        relative to the image (overrides --padding for y-axis)
  -fs, --font-size FONT_SIZE
                        set the font size of watermark text (default: '12')
  -fc, --font-color FONT_COLOR
                        set the font color of watermark text (default:
                        'white')
  -ow, --outline-width OUTLINE_WIDTH
                        set the outline width of the watermark text (default:
                        '2')
  -oc, --outline-color OUTLINE_COLOR
                        set the outline color of the watermark text (default:
                        'black')
  -a, --alpha ALPHA_VALUE
                        set the transparency of the watermark text (0-255,
                        where 0 is fully transparent and 255 is fully opaque;
                        default: '128')
  --camera              use camera metadata as watermark
  -l, --lowercase, --no-lowercase
                        lowercase the watermark text

fotolab env

fotolab env -h

usage: fotolab env [-h] [-o] [-q] [--debug] [--dry-run]

options:
  -h, --help       show this help message and exit
  -o, --overwrite  overwrite existing image
  -q, --quiet      suppress all logging
  --debug          show debugging log and stacktrace
  --dry-run        print the output filenames without writing any files

fotolab face

fotolab face -h

usage: fotolab face [-h] [-o] [-q] [--debug] [--dry-run] [-op]
                    [-od OUTPUT_DIR] [-of OUTPUT_FILENAME] [-j JOBS] [-m MODE]
                    [-f FACTOR]
                    IMAGE_PATHS [IMAGE_PATHS ...]

positional arguments:
  IMAGE_PATHS           set the image filenames

options:
  -h, --help            show this help message and exit
  -o, --overwrite       overwrite existing image
  -q, --quiet           suppress all logging
  --debug               show debugging log and stacktrace
  --dry-run             print the output filenames without writing any files
  -op, --open           open the image using default program (default:
                        'False')
  -od, --output-dir OUTPUT_DIR
                        set default output folder (default: 'output')
  -of, --output-filename OUTPUT_FILENAME
                        set output filename (default: 'None')
  -j, --jobs JOBS       process images in parallel using the given number of
                        worker processes (default: '1')
  -m, --mode MODE       set the anonymization effect (default: 'mosaic')
  -f, --factor FACTOR   set the mosaic block size factor (default: '15')

Copyright and License

This program is free software: you can redistribute it and/or modify it under the terms of the GNU Affero General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Affero General Public License for more details.

You should have received a copy of the GNU Affero General Public License along with this program. If not, see https://www.gnu.org/licenses/.

The fish logo used in the documentation generated by Sphinx is a public domain drawing of male freshwater phase [Sockeye (red) salmon (Oncorhynchus nerka)] (https://en.wikipedia.org/w/index.php?oldid=1186575702) from https://commons.wikimedia.org/entity/M2787002.

Metadata

Release files for fotolab 0.48.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for fotolab 0.48.0
File	Size	Uploaded	Provenance
fotolab-0.48.0.tar.gz	65.4 kB	Oct 18, 2026	Without provenance	Details

Built distribution (wheel)

Table of built distributions (wheels) for fotolab 0.48.0
File	Interpreter	ABI	Platform	Reset
fotolab-0.48.0-py3-none-any.whl 65.4 kB Oct 18, 2026 Without provenance	Python 3	none	any	Details

Total release size: 130.8 kB

Release files / fotolab-0.48.0.tar.gz

Download URL	fotolab-0.48.0.tar.gz
Size	65.4 kB
Tags	Source
SHA-256 checksum How to use checksums	`3a9d842b3594b212a84f3e67c0fb7493915eb2b46df6d930ce7960068689aedf`
BLAKE2b-256 checksum How to use checksums	`cb611416937d9608c1d71720591bfab876e87ce904e35908323d7cebced05c72`
Upload date	Oct 18, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`uv/0.13.1 {"installer":{"name":"uv","version":"0.13.1","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"26.10","id":"stonking","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}`

Release files / fotolab-0.48.0-py3-none-any.whl

Download URL	fotolab-0.48.0-py3-none-any.whl
Size	65.4 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`527c98192d1d838c82d1435590e5e33c25a204634f31f7fc28c9687b71aad95b`
BLAKE2b-256 checksum How to use checksums	`7d80b8db0f97803688b9f10eaa3aae579aeceae51fe3005ff6d3076245b1282d`
Upload date	Oct 18, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`uv/0.13.1 {"installer":{"name":"uv","version":"0.13.1","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"26.10","id":"stonking","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}`

Security for fotolab 0.48.0

Report project as malware

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.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.