Imaegete

A FOSS image viewer built with PyQt6.

Imaegete is currently packaged and tested as a Linux desktop application. Some Qt-backed internals are portable, but Linux is the supported release target for published wheels.

Features

• Fast keyboard-driven navigation
• Zoom + pan
• Animated GIF support
• Slideshow with tap-tempo
• On-disk metadata cache + in-memory pixmap cache
• Folder watching (auto-refresh when files change)
• Vim-inspired command mode (:) and filename search (/)
• Category sorting (move current image into configured folders)

Install

# from PyPI
pip install imaegete

# from source (development)
# canonical source: https://latebrum.com/git/actx/Imaegete/
# public mirror:    https://codeberg.org/aaron_colichia/Imaegete
cd Imaegete
pip install -r requirements-dev.txt
pip install -e .

Usage

imaegete [options] [paths...]

Examples:

# scan a directory
imaegete ~/Pictures

# open a single file (also uses its parent directory as the effective root)
imaegete ~/Pictures/foo.jpg

# playlist/selection-only mode: open exactly these files (no directory scanning)
imaegete 0.jpg 1.jpg 2.jpg

Playlist mode (multi-select)

If you launch Imaegete with multiple file paths (for example via a file manager “Open With” multi-select), it runs in selection-only / playlist mode:

• the image list is exactly the argv file list (deduped, order preserved)
• folder scanning does not run
• watchers may refresh/notice deletions, but will not inject unrelated files

Common options

• --start_dirs DIR [DIR ...] scan one or more folders (default: .)
• --categories CAT [CAT ...] category folder names (enables move-to-category keys)
• --sort_dir DIR base directory to create category folders in (defaults to start_dirs)
• --cache_dir DIR cache location (default: ~/.config/Imaegete/cache)
• --cache_size MB cache size in MB
• --clear_cache clear cache and exit

For the full CLI: imaegete --help

Declarative GlavnaQt layouts

Imaegete uses GlavnaQt's data-only layout layer for its default chrome. A custom YAML/TOML layout can be loaded with:

imaegete --layout-file layout.yaml

During development, add hot reload:

imaegete --layout-file layout.yaml --dev-layout-hot-reload

Layout files describe sections only. Runtime widgets, including the image canvas, remain owned by Imaegete and are reattached by section name during layout compilation/reload.

Controls

Keyboard shortcuts

All shortcuts below are active in normal mode (i.e. when you are not typing into the : or / bars). Press Esc to leave command/search and return to normal mode.

• Next image: Right / j
• Previous image: Left / k
• First image: Home / gg
• Last image: End / G
• Random image / toggle shuffle mode: R
• Toggle slideshow: S
• Slideshow/GIF/flood-zoom speed up: ]
• Slideshow/GIF/flood-zoom speed down: [
• Zoom in: +
• Zoom out: -
• Reset zoom (fit-to-window): =
• Flood-zoom (auto-zoom) toggle: \\
• Toggle fullscreen: F
• Delete current image: Delete
• Undo last delete/move: U
• Move to category 1..9 (if configured): 1 … 9
• Enter command mode: :
• Enter filename search: /
• Exit command/search bars: Esc
• Quit: Q

Mouse

• Zoom: mouse wheel
• Pan: left-click + drag (only when zoomed in past “fit to window”)

Slideshow tap-tempo

While slideshow is running, manual navigation taps set the interval:

• two taps establish a tempo; additional taps refine it
• direction changes reset the tap sequence
• taps time out after inactivity

Keys that count as taps: Right/j (next), Left/k (previous), R (random).

Category moves

If you pass --categories (or set categories in config), you can move the current image into a category folder:

• press 1..9 to move to the corresponding category (first 9 only)
• or use :m <category> / :m <N> in command mode

Vim-style modes

Command mode (:)

Type : to open the command bar, then press Enter.

• :q / :quit / :exit — quit
• :n / :next — next image
• :p / :prev / :previous — previous image
• :first / :last / :rand (:random) — jump
• :del / :delete / :rm — delete current image
• :u / :undo — undo last move/delete
• :m <category> or :m <N> — move to category by name or 1-based index
• :fs (:fullscreen) — toggle fullscreen
• :ss (:slideshow) [on/off] — toggle or set slideshow
• :<N> — jump to 1-based index (e.g. :12)

Filename search (/)

Type / to open the search bar.

• start typing to live-filter the image list
• select from the popup list (mouse or keyboard) and press Enter
• Esc exits search without jumping

License

This repository ships under 0BSD; see LICENSE.

Licensing / provenance notice

This repository may include AI-generated material and minimal human-authored material. To the extent any portion of this repository is not copyrightable, it is made available without restriction.

No bundled third-party source files or assets were identified in the shipped source tree during the current audit. External runtime/build dependencies are not vendored into this repository and remain subject to their own licenses.