Attachment Atlas

Find duplicate images, clean up unused images, and keep your Obsidian notes linked to the right files.

Attachment Atlas helps you review local images, preview changes, and recover past cleanup operations. It runs entirely inside your vault, with no account or network connection required.

简体中文 · Installation · Quick start · Support development · Changelog

What you can do

• Consolidate duplicate images. Keep one copy of byte-identical images and update supported references before recycling the extra copies.
• Find unused images. Review images with no detected references and choose which ones to recycle.
• Inspect storage and references. See image sizes, dimensions, and reference locations; browse the largest images first.
• Review changes before applying them. Check exact file paths and note changes in a preview, with another check before execution.
• Recover a cleanup. Restore original images and references from operation history, with protection for conflicting later edits.
• Manage recovery storage. See how much space recovery records use and permanently clear selected records when you no longer need them.

Supported: Obsidian desktop 1.13.0 or later; static PNG, JPEG, and WebP images. The interface follows Obsidian's language setting: Chinese locales use Simplified Chinese, and all other locales use English.

Installation

Community plugins

In Obsidian, open Settings → Community plugins → Browse, search for Attachment Atlas, then install and enable it. If the plugin is not listed in your directory yet, use the GitHub Release installation below.

GitHub Releases

1. Open GitHub Releases and download main.js, manifest.json, and styles.css from the same release.
2. Create an attachment-atlas folder inside your vault's .obsidian/plugins/ directory and place all three files inside it.
3. Reload Obsidian. Open Settings → Community plugins and enable Attachment Atlas.

The installed folder should contain these files:

<vault>/.obsidian/plugins/attachment-atlas/
├── main.js
├── manifest.json
└── styles.css

You do not need Node.js or npm to install a released version. The source ZIP and tarball generated by GitHub are not installable plugin bundles. Developers can create a local installation ZIP with npm run package.

Quick start

1. Click the Attachment Atlas images icon in the ribbon, or run Attachment Atlas: Open image organizer from the command palette.

2. Select Scan vault. Scanning reads images and their references without changing notes or attachments.

3. Choose the tab for your task:

   Tab	Use it to
   Exact duplicates	Choose a copy to retain and preview a duplicate merge.
   Unreferenced	Select unused images and preview recycling.
   Large images	Inspect images in descending file-size order.
   Needs review	Read the reasons an image or reference source needs attention.
   History	Restore a cleanup or manage its recovery data.

4. Review the preview's file paths and proposed changes, then confirm the operation you want to run.

Use Filter by path to narrow the displayed results. To restrict which images are scanned, set Image scope in the plugin settings. Reference checks still cover supported sources throughout the vault.

Merge duplicate images

1. Open Exact duplicates after a scan.
2. Review a group and choose the image to retain.
3. Select Preview merge. Check which copies will be recycled and which references will change.
4. Confirm the listed operation.

For example, if images/photo.png and notes/photo-copy.png contain exactly the same bytes, you can retain images/photo.png. Supported references to the other copy are updated to the retained image before the extra copy is recycled.

Duplicate groups contain byte-identical files. Resized, recompressed, or visually similar images are not treated as exact duplicates.

Images referenced by Excalidraw drawings must be retained because the plugin does not rewrite drawing files. Attachment Atlas recommends retaining a drawing-used copy so other eligible duplicates can still be merged.

Recycle unused images

1. Open Unreferenced after a scan.
2. Review the image paths and reference information, then select the images you want to recycle.
3. Select Preview recycling, check the file list, and confirm.

There is no waiting period after a successful reference check. Protected images and images whose reference status is uncertain cannot be selected.

If reference coverage is incomplete, this tab is called Potentially unreferenced. Merging and recycling are disabled until you resolve the blocking issues. Select View blocking issues, inspect Needs review, and scan again after addressing the reported sources.

Restore a cleanup

1. Open History and find the operation you want to undo.
2. Select Preview recovery and review the images and references to restore.
3. Confirm the recovery.

Original images are restored before references. Later note edits or conflicting file paths stop recovery without overwriting the newer content; the recovery materials remain available for you to resolve the conflict.

After every image and reference has been restored and verified, that operation's recovery copies and history record are permanently removed. If restoration succeeds but removing its recovery data fails, History retains the remaining data for you to clear. The restored images and references stay in place.

Free recovery storage

Recycling removes images from their original paths but keeps recovery copies in .attachment-atlas-recovery/. These copies continue to use disk space until you restore the operation or permanently clear its recovery data.

1. Open History and review the total recovery storage and each record's size.
2. Select Clean recovery data on a record, or select multiple records and choose Preview recovery cleanup. Use Empty recovery area to preview clearing all eligible records.
3. Review the paths and size, acknowledge the permanent deletion, and confirm.

Clearing recovery data permanently removes the selected images, note snapshots, and history records. Those operations can no longer be restored through the plugin. Current notes and images are not changed by recovery cleanup.

Unfinished or damaged records are protected. Resolve them before emptying the entire recovery area; eligible records can still be cleared individually. If cleanup is interrupted, select Continue cleanup to preview and finish removing the remaining data.

Records do not expire automatically. Select older than 30 days only selects records for review. Each cleanup handles at most 100 records and 10,000 files, so larger sets must be cleared in batches. An empty .attachment-atlas-recovery/ folder may remain.

Settings

Open Settings → Attachment Atlas, enter paths relative to the vault without a leading slash, then select Save settings.

Setting	What it does	Example
Image scope	Limits the image folder to inspect. Leave empty for the whole vault.	Attachments
Preferred retained folder	Recommends copies in this folder when choosing which duplicate to retain. Drawing-used copies take priority.	Attachments/Keep
Protected paths	Prevents the listed files or folders from being recycled. Enter one path per line.	Attachments/Important

Limiting image scope does not limit reference checks: supported notes, Canvas files, and Excalidraw drawings are still checked across the vault.

Commands

Find these commands in Obsidian's command palette under Attachment Atlas:

Command	Action
Open image organizer	Opens the image management view.
Scan vault images	Opens the view and scans using the configured image scope.
Scan current attachment folder	Scans the attachment folder resolved from Obsidian's attachment preferences for the active note.
Open operation history	Opens History to inspect recovery records.

Reference support

Source	Behavior
Markdown image links and Wiki links	Detects references and updates supported links during a duplicate merge.
Canvas file nodes, group backgrounds, and Markdown in text nodes	Detects references and updates supported links during a duplicate merge.
Excalidraw Markdown drawings, including compressed data, and standalone .excalidraw files	Scans without editing drawings; referenced images are protected individually.
YAML and HTML	Does not rewrite these references; detected reference hints can protect affected images.

Unsupported or damaged sources, including drawings and Bases, can block reference coverage. Review Needs review before making changes. External applications and hidden configuration are outside the scan's coverage.

Common questions

Why are merge or recycle buttons disabled?

Read the reason shown beside the action. Common causes include incomplete reference coverage, a protected image, a running task, or unfinished recovery work. Resolve the reported issue in Needs review or History, then scan again.

Why did the scan results disappear after I edited a note or image?

Vault changes invalidate earlier scan results. Scan again before previewing another operation so the plan uses current files and references.

Does Large images compress or convert my images?

It lists images by size for inspection. The plugin currently manages static PNG, JPEG, and WebP images; it does not compress or convert them, or clean up other attachment types such as PDFs and videos.

Does the plugin use Obsidian's .trash/ or the system trash?

Yes. After verifying its recovery copy in .attachment-atlas-recovery/, the plugin removes each original through Obsidian's file manager, following your deleted-file preference. Depending on that preference, Obsidian may place another copy in .trash/ or the system trash. The plugin does not manage or empty either trash location.

Why has disk usage not dropped after cleanup?

Recovery copies still take space. After reviewing the result, use History → Clean recovery data to remove them permanently. Any copies in Obsidian or system trash must be managed separately. Storage totals cover plugin recovery files, excluding trash, filesystem metadata, sync history, and external backups.

How do I change the interface language?

Change Obsidian's language and reload the app to refresh command names and open views. Chinese language settings display Simplified Chinese; all other language settings display English.

Privacy and recovery data

Attachment Atlas processes files locally inside the current vault. It requires no account, sends no network requests, and collects no telemetry.

Scanning enumerates vault file paths so reference checks cover supported sources throughout the vault, even when the image scope is narrower. Node.js filesystem access is limited to reading path metadata with lstat() to reject symbolic links at the vault root and along each accessed path. File content reads, writes, and deletion use Obsidian APIs. Clipboard access only writes a vault-relative folder path when you click Copy recovery folder path; the plugin never reads clipboard contents.

Recovery data includes original images, affected note content, and operation records. It is stored together in .attachment-atlas-recovery/ without additional encryption. Sync and backup behavior depends on your vault settings. Keep these materials until you restore the operation or confirm permanent cleanup.

Support development

Attachment Atlas is free to use. If it helps you, an optional donation supports ongoing development and maintenance. Thank you!

Choose the QR code for your payment app: WeChat Pay and Alipay use different codes.

WeChat Pay · 微信支付	Alipay · 支付宝
Scan with WeChat	Scan with Alipay

Open the WeChat Pay QR code · Open the 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 setup, testing, and release instructions are in CONTRIBUTING.md.

License

MIT © 2026 gua. Third-party licenses are listed in THIRD_PARTY_NOTICES.md.