cullet

Keyboard-driven photo viewer for going through a folder fast: step, zoom, rotate, delete, move into target folders, tag, and review duplicates. Press h in the viewer for the keys, or tap Alt for a menu of everything they do.

Install

Requires python>=3.10

uv tool install cullet

or pip install cullet into an environment of your choice. Rotating JPEGs losslessly needs the jpegtran binary, which comes with libjpeg-turbo on most distributions.

Finding duplicates and fixing rotations need torch, which comes with the full extra:

uv tool install "cullet[full]"

Open with

To get cullet into the "Open with" menu of the file manager for photos and folders, install the desktop file of this repository:

curl -o ~/.local/share/applications/cullet.desktop https://raw.githubusercontent.com/simon-ging/cullet/main/packaging/cullet.desktop
update-desktop-database ~/.local/share/applications
# optional, make it the default for photos
xdg-mime default cullet.desktop image/jpeg image/png

This needs the cullet command on the PATH of the desktop session, uv tool install puts it into ~/.local/bin.

Usage

cullet /path/to/photos
cullet /path/to/photos/IMG_1234.jpg
cullet /path/to/photos -a ../good -a ../maybe -T sun -T portrait
cullet /path/to/photos --dedup

The number keys move the image into the target folders (-a) and toggle the tags (-T), in the order they are given. Deleted files are moved to the system trash, never removed (--trash_dir puts them into a folder of your choice instead), and every file operation can be undone with u. cullet --help lists all options.

Command line tools

They only log what they would do until -w is given. Each has --help.

cullet-dedup-videos /path/to/videos -Q /path/to/quarantine -w
cullet-downscale-images /path/to/photos -s 1080 -w

Install locally and run tests

Clone repository and cd into. Setup python 3.10 or higher.

Dev build: install the clone as the cullet command, with torch, so code changes are live:

uv tool install --editable ".[full]"

Note: The tests that need torch are skipped unless it is installed.

pip install -e .[full,dev]
pylint src

# run tests
python -m pytest --cov
pylint tests