EzImage
Kiang315 downloadsUpload images to cloud storage (R2/S3) with automatic compression. Paste or drag images to get a Markdown link instantly.
- Overview
- Scorecard
- Updates17
EzImage for Obsidian
Paste or drag an image — upload to the cloud or save to vault, your choice.
English | 简体中文
Features • Installation • Configuration • Usage • Roadmap • Feedback
EzImage for Obsidian solves the fundamental pain point of image management in Obsidian: pasted images pollute your vault with local binary files, or worse, reference paths that break across machines. EzImage intercepts every paste and drop event and either uploads the image to your cloud storage (inserting a clean Markdown URL) or saves it to the vault via a wikilink — whichever mode you prefer, switchable at any time from the status bar.
✨ Features
- 🖼️ Seamless Paste Interception — Paste an image anywhere in your notes; EzImage intercepts the event before Obsidian, then either uploads it or saves it locally depending on the current mode.
- 🖱️ Drag & Drop Support — Drag image files directly from Finder / Explorer into the editor. EzImage copies the file into your vault or uploads it — not just references the original path.
- ☁️ Upload Mode — Images are uploaded to Cloudflare R2 and a
link is inserted. Zero local files, zero broken paths. - 💾 Local Save Mode — Images are saved to your vault's configured attachment folder and inserted as
![[wikilink]]. Fully managed by Obsidian's native structure. - ⚡ Mode Toggle — Switch between Upload and Local Save mode via the Settings toggle or Command Palette (
EzImage: Toggle Local Save Mode). The status bar always shows the current mode at a glance. - 📉 Automatic WebP Compression — Powered by
browser-image-compression. Images are converted to WebP and resized before upload, reducing file size without visible quality loss. EXIF metadata is stripped automatically during conversion. - 🔏 EXIF Metadata Stripping — When compression is disabled, EzImage redraws the image via Canvas before upload, removing GPS location, device info, and other metadata. No extra dependency required.
- 🛡️ Upload Reliability — Failed uploads are automatically retried up to 2 times with back-off. Credential errors surface a clear "check Settings" message; network errors prompt to check your connection.
- 📂 Flexible Path Templates — Full control over the upload path using variables:
{yyyy}{MM}{dd}{timestamp}{random}{name}{ext}. - 🌐 Language Support — Settings UI available in English and 中文, or auto-detected from Obsidian.
- 🔒 Local Signing — AWS Signature V4 is computed entirely on-device using the Web Crypto API. Your credentials never leave your machine.
📦 Installation
Method A: Community Plugins (Recommended)
- Open Obsidian → Settings → Community Plugins → Browse.
- Search for EzImage and click Install, then Enable.
Method B: Manual (BRAT / direct)
- Download
main.js,styles.css, andmanifest.jsonfrom GitHub Releases. - Copy both files to
<your-vault>/.obsidian/plugins/ezimage/. - Reload Obsidian and enable the plugin under Settings → Community Plugins.
⚙️ Configuration
Open Settings → EzImage and fill in your credentials and preferences.
Cloudflare R2
| Field | Description |
|---|---|
| Account ID | Found on the right sidebar of your Cloudflare dashboard |
| Access Key ID | R2 API token — requires Object Read & Write permission |
| Secret Access Key | Paired secret for the access key |
| Bucket Name | The R2 bucket to upload images into |
| Public URL | Your bucket's public URL, e.g. https://pub-xxx.r2.dev or a custom domain |
How to get R2 credentials
- Go to Cloudflare Dashboard → R2 → Manage API tokens.
- Create a token with Object Read & Write permission scoped to your bucket.
- Copy Account ID, Access Key ID, and Secret Access Key.
- Make sure your bucket has Public Access enabled (or use a custom domain with a Worker).
Image Processing
| Option | Default | Description |
|---|---|---|
| Compress Images | on |
Convert to WebP before upload — also strips EXIF automatically |
| Formats to Keep Original | gif |
Extensions that bypass conversion, resizing, and metadata stripping. Animated GIF, WebP, PNG, AVIF, and SVG files are also detected from their contents and preserved automatically |
| Strip EXIF Metadata | on |
Remove GPS, device info, and other metadata. Only applies when compression is off (compression already strips EXIF via WebP conversion) |
| Max Width | 1920 |
Resize if wider than this (px). 0 = no limit |
| Quality | 85 |
WebP quality (1–100) |
| Max File Size (MB) | 20 |
Files larger than this are rejected before upload. 0 = no limit |
| Path Template | {yyyy}/{MM}/{timestamp}-{random}.{ext} |
Upload path pattern — live preview shown in Settings |
| Markdown Image Template |  |
Markdown inserted after upload. Customize it to include file names or dates |
Template variables: {yyyy} {MM} {dd} {hh} {mm} {ss} {timestamp} {random} {name} {ext}
Markdown image variables: {{url}} {{name}} {{fileName}} {{ext}} {{date}} {{time}}
Examples:
General
| Option | Default | Description |
|---|---|---|
| Default to Local Save mode | off |
When enabled, images are saved to your vault by default instead of being uploaded. Can be toggled at any time via the status bar. |
| Language | Auto |
Language used in the settings panel. Options: Auto (follow Obsidian), English, 中文. |
🚀 Usage
| Action | How |
|---|---|
| Paste image | Copy any image → paste in editor — processed automatically based on current mode |
| Drag & drop | Drag image file(s) from your file manager into the editor |
| Upload from file | Command Palette → EzImage: Upload Image from File |
| Upload clipboard | Command Palette → EzImage: Upload Clipboard Image |
| Batch upload local images | Command Palette → EzImage: Batch Upload Local Images (entire vault)Right-click on file/folder → EzImage: Batch Upload Local Images (scoped) |
| Toggle mode | Settings toggle, or Command Palette → EzImage: Toggle Local Save Mode |
| Context menu | Right-click in editor → EzImage options |
Status Bar
The status bar item is a read-only indicator of the current mode:
| Display | Mode |
|---|---|
☁ EzImage (dimmed) |
Upload mode — images go to R2 |
🖴 Local Save (bright) |
Local Save mode — images go to vault |
To switch modes, use the Settings toggle or Command Palette → EzImage: Toggle Local Save Mode (bindable to a hotkey). The tooltip follows your configured language.
Note: EzImage only intercepts paste/drop events when R2 is configured. If credentials are missing, Obsidian's default behaviour (local save) is preserved regardless of mode.
🗺️ Roadmap
- Cloudflare R2 support
- Automatic WebP compression with EXIF stripping
- Paste & drag-drop interception
- Flexible path templates with live preview
- Local Save mode with status bar indicator
- Language support (EN / 中文)
- File size limit & input validation
- Auto-retry on network errors
- EXIF metadata stripping (when compression is off)
- Batch upload existing local images in vault
- AWS S3 / generic S3-compatible providers
- Aliyun OSS & Tencent COS
- GitHub / Gitee image hosting mode
- Upload history panel
🤝 Contribution & Feedback
Found a bug or have a feature request? Please open an issue.
Pull requests are welcome. See the development setup below.
Development
git clone https://github.com/keepwonder/ezimage-obsidian.git
cd ezimage-obsidian
npm install
# Watch mode (outputs main.js)
npm run dev
# Production build
npm run build
Copy main.js, styles.css, and manifest.json into your vault's plugin folder to test locally.
📞 Contact & Support
💬 Feedback
Scan the QR code below to add the author on WeChat, please mention "EzImage":
Scan to get technical support
☕ Support the Author
If EzImage has improved your workflow, feel free to buy me a coffee!
WeChat Pay |
Alipay Pay |
Developed with ❤️ by Kiang