Local Image Compress

Compress PNG and JPEG files directly in your Obsidian vault on your computer, without cloud services or APIs. Reduce the disk space used by images by 30–70% without sacrificing quality.

Read in your language: English • العربية • Deutsch • Español • فارسی • Français • Bahasa Indonesia • Italiano • Nederlands • Polski • Português • Português (Brasil) • Русский • ไทย • Türkçe • Українська • Tiếng Việt • 日本語 • 한국어 • 中文简体 • 中文繁體

Table of contents

• Features
• Supported formats
• Settings
• How it works
• Data storage and backups
• Automation
• Interaction with Paste Image Rename
• Privacy and external behavior
• Tips
• FAQ
• License

Features

• Local compression: PNG and JPEG images are compressed locally.
• Commands:
  • Compress all images in note: Processes images referenced or used in the active note.
  • Compress all images in folder: Lets you select a folder and compresses all supported images inside it, excluding the output folder.
  • Compress all images in vault: Scans the entire vault, excluding the output folder.
  • Move compressed files: Moves compressed results to the original file locations. Before moving, it creates backups of both the original and compressed versions.
• Automation:
  • Automatically compress new files when they are added
  • Background compression after user inactivity when the number of uncompressed images in the vault reaches the threshold.
• UI and convenience:
  • Context menu for files and folders
  • Space savings indicator with a detailed tooltip
  • Status bar progress indicator
• Safety and reliability:
  • Cache of processed files with cache backups
  • Backups created before moving compressed files, with automatic deletion.

Supported formats

• PNG (imagequant WASM pipeline)
• JPEG/JPG (mozjpeg WASM pipeline)

WebP, GIF, BMP, HEIC/HEIF, and AVIF are intentionally skipped in this release because the plugin does not include encoders for those formats.

Settings

How it works

1. Compressed files are saved in the Compressed folder while preserving the original path structure.
2. The cache records processed files and their original sizes to prevent repeated compression and calculate savings correctly.
3. “Move compressed files” moves files from Compressed back to their original locations when the original is inside an allowed root. A backup is created before moving.

Minimum sizes for compression: very small files are usually skipped (<5KB for PNG and <10KB for JPEG).

Internal safety limits are fixed: files larger than 100 MB are skipped before reading, and images above 100 million pixels are skipped after header validation.

Data storage and backups

• Primary cache: stored in the plugin folder.
• Cache backups: stored in Vault/.local-image-compress/backups/cache/; up to 50 files are kept.
• Image backups: stored in Vault/.local-image-compress/backups/originals/; created before the originals are replaced.

Automation

• Enabling “Background compression” makes two sliders available:
  • Background compression threshold: 10–1000 images, default 50.
  • Inactivity threshold: 1–60 minutes, default 2.
• Enabling “Keep backups, days” shows the retention-period slider.
• Enabling “Auto-move compressed files” shows the file-count threshold. On startup, moving begins when the number of files in Compressed meets or exceeds the threshold.

Interaction with Paste Image Rename

This plugin temporarily disables the third-party plugin obsidian-paste-image-rename while compressing or moving files. This protection cannot be turned off because mapping compressed output to its original depends on newly created files not being renamed by another plugin.

Privacy and external behavior

• Network: the plugin makes no runtime network requests. PNG/JPEG codecs are bundled in main.js; images are not uploaded.
• Telemetry and ads: no analytics, telemetry, crash reporting, tracking, dynamic ads, or self-update mechanism is included.
• Accounts and payments: no account, subscription, license key, or payment is required. The optional funding link in the manifest is never accessed by the plugin.
• Vault files: the plugin reads supported images selected by commands, automation, or allowed roots. It writes compressed output to the configured vault-relative folder and replaces originals only through the documented move or auto-move workflow after creating backups.
• Local state: cache data is stored in the plugin folder. Cache and move backups are stored under Vault/.local-image-compress/backups/.
• External files: plugin-managed data stays inside the current vault. The “Open folder” actions only ask the operating system to reveal documented backup folders; they do not transmit data.
• Other plugins: obsidian-paste-image-rename may be temporarily disabled during compression or move operations, as described above, and is then restored with ownership checks.

Tips

• Reasonable quality ranges: PNG 65-80, JPEG 75-90.
• Configure “Allowed roots” if you want to compress only in specific folders, such as files/ or images/.
• Use background compression when the vault contains many uncompressed images.

FAQ

The plugin reports that the WebAssembly modules failed to initialize. Reload the plugin. If the error occurs again, include your Obsidian version, platform, and console error in the bug report.

Where are compressed files stored? They are stored in Compressed by default. To replace the originals, use “Move compressed files”.

How are savings calculated? Savings are exact when the cache contains the original and output sizes. For uncompressed PNG/JPEG files, the plugin uses conservative estimates with capped ratios; the current sizes of compressed files are read from disk when needed.

License

GPL-3.0-or-later. Third-party licenses and notices: THIRD_PARTY_NOTICES.md.