README file from
GithubAttachment Atlas
Find duplicate images, clean up unused images, and keep your Obsidian notes linked to the right files.
- Merge exact duplicates in batches: choose a retained image and explicit copies in each group, then review and confirm the selected groups together.
- Clean up unused images: review images with no detected references and choose which to recycle.
- Inspect large images: browse by file size and check dimensions and reference locations.
Preview changes before applying them. Everything runs locally inside your vault, with no account, network requests, or telemetry.
Supported: Obsidian desktop 1.8.7+; static PNG, JPEG, and WebP images. Interface: English and Simplified Chinese. Settings search integration is available on Obsidian 1.13.0+. Bases .base files are scanned only through a restricted static subset (static table views and fixed image("path") formulas); dynamic formulas, executable base blocks, and unknown views keep merging and recycling disabled.
Installation
Open Settings → Community plugins → Browse, search for Attachment Atlas, then install and enable it. If it is not listed yet, install from GitHub Releases below.
- Download
main.js,manifest.json, andstyles.cssfrom the same release. - Place all three files in your vault's
.obsidian/plugins/attachment-atlas/folder, creating it if needed. - Reload Obsidian and enable Attachment Atlas in Settings → Community plugins.
No Node.js or npm is needed. GitHub's source ZIP and tarball are not installable plugin bundles.
Quick start
- Click the Attachment Atlas images icon in the ribbon, or run Attachment Atlas: Open image organizer from the command palette.
- Select Scan vault. Scanning does not change notes or images.
- In Exact duplicates, choose a retained image and copies to delete in each group. Use Preview selected groups to review all selected groups together. In Unreferenced, select images, click Recycle selected images, and confirm in the dialog. Recycling reuses the scan without fingerprinting all images again.
- Check the file paths and reference changes, then confirm. A merge accepts up to 100 selected copies totaling 192 MiB across all groups; retained and unselected images do not count toward these limits.
- Review the session result for completed, partially completed, unprocessed, or unconfirmed groups. If cleanup stops, scan again and preview the remaining work; applied changes are kept.
To limit image scanning or protect folders, open Settings → Attachment Atlas.
Recycling
- Reference coverage: supported Markdown and Canvas references can be updated during merges. Excalidraw drawings are scanned without modification, and their images are protected. Bases
.basefiles are read through a restricted static subset: a fixedimage("path")formula registers a read-only reference and its image is retained, while unrelated copies can still be merged or recycled. Frontmatter continues to act only as an existing protective hint. Dynamic formulas, executablebaseblocks, and unsupported views keep merging and recycling disabled; this version does not claim full Bases support, and rescanning does not make an unsupported format supported. Inspect Needs review for the source, reason, and next step. - Deletion and restoration: images follow Settings → Files and links → Deleted files: system trash, the vault’s
.trash/folder, or permanent deletion. Choose a trash option if you want to restore images later; permanently deleted images cannot be recovered from trash. Reference changes made during a merge are not automatically undone.
Support development
Attachment Atlas is free to use. Optional donations support development and maintenance.
Use the QR code for your payment app.
| WeChat Pay · 微信支付 | Alipay · 支付宝 |
|---|---|
Open WeChat Pay QR code · Open Alipay QR code
Feedback and contributing
Report a bug or request a feature with reproduction steps and a small, non-private example. For sensitive reports, follow SECURITY.md. Development instructions are in CONTRIBUTING.md.
License
MIT © 2026 gua. See third-party licenses.