QViewer

A fast, lightweight image viewer built with PyQt5 and optimized with Cython. Navigate through multiple images with keyboard shortcuts!

Features

• 🖼️ View images from local files or URLs
• ⚡ Auto-scaling to fit screen
• 🎨 Frameless window design
• ⌨️ Keyboard navigation (Arrow keys, Space)
• 🔄 Cycle through multiple images
• 📁 Directory scanning (with recursive depth control)
• 📋 Clipboard support
• 🚀 Cython-optimized for performance

Supported Formats

JPG, JPEG, PNG, GIF, BMP, TIFF, TIF, WEBP, ICO, SVG, HEIC, HEIF, AVIF, JFIF, APNG

Installation

pip install qviewer

Usage

Command Line

# View single image
qviewer image.jpg

# View multiple images (navigate with arrow keys)
qviewer img1.jpg img2.png img3.gif

# View all images in a directory
qviewer /path/to/images/

# View images in directory (max depth 2 subdirectories)
qviewer -d 2 /path/to/images/

# View only current directory (no subdirectories)
qviewer -d 0 /path/to/images/

# Mix files and directories
qviewer image1.jpg /path/to/more/images/ image2.png

# View image from URL
qviewer https://example.com/image.png

# Load from clipboard
qviewer c

Keyboard Shortcuts

• Arrow Right / Arrow Down / Space - Next image
• Arrow Left / Arrow Up - Previous image
• Q / Escape - Quit

Python API

from qviewer import show, collect_all_images

# View single image
show(['/path/to/image.jpg'])

# View multiple images
images = [
    '/path/to/img1.jpg',
    '/path/to/img2.png',
    'https://example.com/img3.gif'
]
show(images)

# Collect images from directory and view
images = collect_all_images(['/path/to/images'], max_depth=2)
show(images)

Command Line Options

usage: qviewer [-h] [-d N] [paths ...]

positional arguments:
  paths              Image file(s), URL(s), or directory path(s)
                     Use "c" to load from clipboard

optional arguments:
  -h, --help         show help message and exit
  -d N, --depth N    Maximum directory recursion depth
                     (default: infinite, 0: current dir only)

Requirements

• Python >= 3.7
• PyQt5 >= 5.15.0
• requests >= 2.25.0
• clipboard >= 0.0.4

Examples

Browse vacation photos

qviewer ~/Pictures/Vacation2024/

Compare multiple screenshots

qviewer screenshot1.png screenshot2.png screenshot3.png

Review images from multiple directories

qviewer ~/Downloads/ ~/Pictures/Recent/ -d 1

Quick view from clipboard

# Copy image URL or path, then:
qviewer c

👤 Author

Hadi Cahyadi

Support me on Patreon