A lightweight, no-nonsense media viewer for local directories
Click on the image for a demonstration video.
I was fed up with overly complex gallery applications that process, copy, and transcode files unnecessarily. LocalPics is born out of the need for a simple, efficient way to view files in directories without any processing overhead.
Just point it at a directory, and it instantly creates a beautiful, browser-based interface to explore your files - no database, no complicated setup, no file manipulation.
- 🚀 Zero processing by default - files are served directly from the source directory
- 📱 Responsive layout with lazy loading for browsing large directories
- 🖼️ Media-specific viewers for images, videos, audio, PDFs, and code files
- 📊 File categorization by type (images, videos, audio, text, code, etc.)
- 📷 EXIF data extraction for images with GPS location mapping
- 🔄 Dynamic navigation with keyboard shortcuts
- 📝 Code syntax highlighting for various programming languages
- 📦 Single binary with embedded template - no dependencies to install (unless you want video thumbnails)
- 🎞️ Video thumbnails with intelligent caching for faster browsing (requires ffmpeg, and does a bit of server-side processing)
Visit the Releases page and download the appropriate binary for your platform.
- FFmpeg (optional, required only for video thumbnail generation)
# Create a default configuration file
./localpics -create-config
# Use a custom configuration file
./localpics -config /path/to/my/config.json
# Command line flags override config file settings
./localpics -config /path/to/config.json -host 192.168.1.100:8080
# Basic usage (temporary output directory will be created)
./localpics -indir /path/to/your/media
# Specify an output directory
./localpics -indir /path/to/your/media -outdir /path/to/output
# Enable file deletion (use with caution)
./localpics -indir /path/to/your/media -delete
# Serve on a specific IP address and port
./localpics -indir /path/to/your/media -host 0.0.0.0:8080
# Enable video thumbnail generation (requires FFmpeg)
./localpics -indir /path/to/your/media -thumbnails
# Customize thumbnail caching
./localpics -indir /path/to/your/media -thumbnails -thumb-cache /path/to/cache -thumb-pregenerate 100After starting, open the displayed URL in your browser to view your files.
LocalPics is available as a Docker container, making it easy to deploy without installing any dependencies.
# Pull the latest version
docker pull ghcr.io/tuxx/localpics:latest
# Or a specific version
docker pull ghcr.io/tuxx/localpics:1.2.3# Run with default settings (temporary output directory)
docker run -p 8080:8080 -v /path/to/your/media:/data ghcr.io/tuxx/localpics:latest -indir /data -host 0.0.0.0:8080Create a config file on your host:
{
"input_dir": "/data",
"host": "0.0.0.0:8080",
"recursive": true,
"thumbnails": false,
"thumbnail_cache": "/app/thumbnails",
"thumbnail_pregenerate": 50,
"debug_log": false
}Run with your configuration:
docker run -p 8080:8080 \
-v /path/to/your/media:/data \
-v /path/to/config.json:/app/.config/localpics/localpics.json \
-v /path/to/thumbnail/cache:/app/thumbnails \
ghcr.io/tuxx/localpics:latestversion: '3'
services:
localpics:
image: ghcr.io/tuxx/localpics:latest
ports:
- "8080:8080"
volumes:
- /path/to/your/media:/data
- /path/to/config.json:/app/.config/localpics/localpics.json
- /path/to/thumbnail/cache:/app/thumbnails
restart: unless-stopped/data: Mount your media directory here/app/.config/localpics/localpics.json: Mount your configuration file here/app/thumbnails: Persistent storage for video thumbnails
If you want to test changes or build the container locally:
# Build from source
make docker
# Run your local build
docker run -p 8080:8080 -v /path/to/your/media:/data localpics:latest -indir /data -host 0.0.0.0:8080| Option | Description |
|---|---|
-config |
Path to config file (default is platform-specific) |
-create-config |
Create a default config file and exit |
-indir |
Required. Directory to scan for media files |
-outdir |
Optional. Directory to write HTML and JSON files |
-delete |
Enable file deletion API (default: false) |
-host |
Host address to serve on (default: localhost:8080) |
-recursive |
Scan directory recursively (default: true) |
-thumbnails |
Enable video thumbnail generation (requires FFmpeg) |
-thumb-cache |
Directory to store video thumbnails (default: "thumbnails") |
-thumb-pregenerate |
Number of video thumbnails to pre-generate at startup (default: 50) |
-log |
Enable debug logging (default: false) |
-v |
Print version information and exit |
- Windows:
%APPDATA%\localpics\localpics.json - macOS:
~/Library/Application Support/localpics/localpics.json - Linux:
~/.config/localpics/localpics.json
- Go 1.16 or newer
- Make (for using the Makefile)
- FFmpeg (for video thumbnail support)
# Clean and build for current platform
make all
# Build for specific architectures
make linux-amd64
make darwin-arm64
make windows-amd64
# Build for all supported platforms
make release-all
# Package builds into archives
make package- Home - View file statistics and category breakdown
- Categories - Browse files by type (images, videos, audio, etc.)
- Image Viewer - View images with EXIF data, navigation, and download options
- Code Viewer - Syntax-highlighted code with full-screen viewing
- Video/Audio - Native HTML5 players with thumbnail previews for videos
- Video Thumbnails - Automatically generated previews for videos with intelligent caching
LocalPics can now generate thumbnails for videos to provide a better browsing experience:
- Automatically extracts a frame from each video to use as a thumbnail
- Intelligently caches thumbnails to avoid regeneration
- Shares thumbnails between similar videos (e.g., episodes of the same series)
- Pre-generates thumbnails at startup (configurable number)
- Enhanced UI with smooth loading animations
This feature requires FFmpeg to be installed on your system.
Contributions are welcome! Please feel free to submit pull requests or open issues to improve the application.
- Go 1.16 or newer
- Make (for using the Makefile)
- Git hooks installed
./.githooks/setup-hooks.sh- prettier (for fixing the html template indenting)
- Fork the repo
- Push your changes and submit a Pull Request
- Bother Tuxx if it sits too long 🙂
- 🔍 Search functionality for finding files quickly
- 🗑 Delete files from the webinterface
- 🌓 Dark mode support
- 📱 Better mobile optimizations
- 🔄 Sorting options (by name, date, size)
- 📂 Archive content viewing
- 🎭 MIME type detection for better file categorization
- 🔒 Basic authentication option
- 🔄 WebSocket support for real-time directory updates
- 🎮 Slideshow mode for images
- 🚦 Improved signal handling for graceful application shutdown on Windows
- 🧹 Better temporary file cleanup mechanisms for Windows environments
- 🔐 Cross-platform file permission handling that respects Windows ACLs
- 🛣️ Robust path handling to prevent issues with Windows file separators
- 🎞️ Platform-specific FFmpeg output capture for thumbnail generation