iTechGuides is reader-supported. When you buy through links on our site, we may earn an affiliate commission. As an Amazon Associate I earn from qualifying purchases. Learn more
Make a complete, untouched copy of your Obsidian vault before changing anything. A safe migration moves the Markdown notes and every file they reference, keeps their relative paths stable, tests a representative sample in the destination, and only then imports the rest. Obsidian supports both Wikilinks and standard Markdown links, but no destination app is guaranteed to understand every Obsidian feature, so links, images, PDFs, aliases, headings, and block references must be checked after import.
What a complete Obsidian migration must preserve
An Obsidian vault is a folder, not just a collection of note text. It can contain Markdown files, images, PDFs, audio, video, canvases, data files, templates, and configuration folders. Notes refer to those files by path. If you export only the .md files, the notes may open while their images and documents appear missing.
There are two separate portability questions:
- Will the destination receive the files? Every attachment and linked document must be copied or imported.
- Can the destination interpret the references? The app must resolve the link syntax, path, heading, alias, or embed used by the note.
Keep the original vault unchanged until the destination passes your checks. That copy is your rollback point if an importer rewrites paths, drops metadata, or converts an unsupported construct incorrectly.
Quick wins for a faster PC:
Scan for outdated or missing drivers - takes under a minuteDriver Scan →Repair Windows errors before they cause bigger problemsFix Now →Fix the driver behind crashes, sound loss and screen glitchesFind Drivers →Step 1: Make an untouched backup
Pause editing and create a complete copy of the vault folder. Copying the folder to another safe location or creating a ZIP archive are both practical approaches. The backup should include hidden files and folders, not only the visible note directories. Do not work directly on this copy during conversion.
#1 Best Overall
- Slim durable design to help take your important files with you
- Vast capacities up to 6TB[1] to store your photos, videos, music, important documents and more
- Back up smarter with included device management software[2] with defense against ransomware
- Help secure your important files with password protection and hardware encryption
- 3-year limited warranty
- Close Obsidian, or at least stop editing while the copy is made, so files are not changing mid-backup.
- Locate the vault’s root folder in your operating system.
- Copy the entire folder to a separate drive or storage location, or create a ZIP containing the entire folder.
- Open the copy and confirm that it contains several Markdown notes, attachment folders, and any other files you expect.
- Label it clearly, such as
Vault-backup-before-migration, and keep it unchanged until verification is complete.
An external drive can be useful for holding the backup, but buying hardware is not required if you already have a reliable destination with enough space. A cloud-synced copy can be an additional safeguard; it should not replace a known-good local copy that you can restore independently.
Step 2: Inventory notes, attachments, and link styles
Before importing, make a simple inventory. You need to know where files live and which features the destination must handle.
- Count or list the Markdown notes, including notes in nested folders.
- Record attachment locations: one central folder, folders beside notes, or subfolders under each note’s folder.
- List file types used in embeds, such as PNG, JPEG, GIF, SVG, PDF, audio, and video.
- Identify notes with aliases, frontmatter, callouts, tasks, templates, canvas files, or plugins that generate special syntax.
- Determine whether internal links are mostly Wikilinks, Markdown links, or a mixture.
- Mark notes containing heading links, block references, links with spaces, and links into nested folders.
This inventory gives you a test plan. A vault with only ordinary note links needs fewer checks than one that relies on block references, embeds, or plugin-generated fields.
Do these 3 things before closing this tab:
1Scan for outdated or missing drivers - takes under a minute2Clear out junk files and repair common Windows errors3Fix the driver behind crashes, sound loss and screen glitchesHow Obsidian links work
Obsidian supports both its compact Wikilink syntax and ordinary Markdown links. A destination that understands only standard Markdown may not resolve Wikilinks without conversion.
| Purpose | Obsidian form | Portable Markdown form | Migration consideration |
|---|---|---|---|
| Link to a note | [[Three laws of motion]] |
[Three laws of motion](Three%20laws%20of%20motion.md) |
The destination must support Wikilinks or you must convert them. |
| Link to a note in a folder | [[Projects/Three laws of motion]] |
[Three laws of motion](Projects/Three%20laws%20of%20motion.md) |
Keep the folder path unchanged during the first transfer. |
| Link to a heading | Heading-target syntax supported by Obsidian | Markdown heading fragment syntax where supported | Test the exact heading link; parsers differ in fragment rules. |
| Reference a specific block | Obsidian block-reference syntax | No universal standard equivalent | Block references are Obsidian-specific and need manual review or a destination-specific conversion. |
When Obsidian creates a Markdown destination containing spaces, it can URL-encode those spaces as %20. Do not casually replace encoded paths with unencoded spaces or remove the .md extension until you know how the target parser behaves.
Rank #2
- 【Plug-and-Play Expandability】 With no software to install, just plug it in and the drive is ready to use in Windows（For Mac，first format the drive and select the ExFat format.
- 【Fast Data Transfers 】The external hard drives with the USB 3.0 cable to provide super fast transfer speed. The theoretical read speed is as high as 110MB/s-133MB/s, and the write speed is as high as 103MB/s.
- 【High capacity in a small enclosure 】The small, lightweight design offers up to 500GB capacity, offering ample space for storing large files, multimedia content, and backups with ease. Weighing only 0.35 Lbs, it's easy to carry "
- 【Wide Compatibility】Supports PS4 5/xbox one/Windows/Linux/Mac and other operating systems, ensuring seamless integration with game consoles,various laptops and desktops .
- Important Notes for PS/Xbox Gaming Devices: You can play last-gen games (PS4 / Xbox One) directly from an external hard drive. However, to play current-gen games (PS5 / Xbox Series X|S), you must copy them to the console's internal SSD first. The external drive is great for keeping your library on hand, but it can't run the new games.
Choose a path strategy before moving files
Obsidian can generate links using the shortest unique path, a path relative to the current file, or an absolute path from the vault. These choices affect portability when folders are reorganized.
| Path style | What it does | Risk during migration |
|---|---|---|
| Shortest unique path | Uses the briefest path that identifies the note. | Another app may not apply the same uniqueness rules, especially when duplicate filenames exist. |
| Relative path | Resolves the target from the linking note’s folder. | Usually predictable when the note and target folders remain together; moving either can break it. |
| Vault-absolute path | Starts from the vault root. | A destination may not have the same root concept or may rewrite the leading path. |
For an initial transfer, preserve the existing folders and filenames instead of optimizing paths. Obsidian can automatically update internal links when a file is renamed inside Obsidian; that setting does not repair arbitrary moves made outside Obsidian and does not make another app understand Obsidian syntax.
PC Slower Than It Used to Be?
A free scan shows the junk files, broken settings and background clutter dragging Windows down - then fixes them in one click.Free scan · Windows 10 & 11Crashes, No Sound, or Screen Glitches?
Random freezes, missing sound and display glitches usually trace back to one bad driver. Find and replace yours safely.Free scan · under a minuteStep 3: Check the destination app’s current importer
The destination determines what conversion is necessary. Consult its current documentation before touching the source vault, because import behavior changes between applications and versions.
- Plain Markdown-folder import: Usually copies files as files. You may need to convert Wikilinks, and attachments generally must be present at the paths referenced by the notes.
- Dedicated Obsidian importer: May translate Wikilinks, frontmatter, or embeds, but confirm which constructs it supports and whether it copies attachments.
- Database-oriented import: May turn each note into a record and treat folders, frontmatter, or file links differently. Verify how original paths and metadata are retained.
Look specifically for documented behavior for:
- Wikilinks and standard Markdown links
- URL-encoded spaces and nested paths
- Images, PDFs, and other embedded files
- Heading links and block references
- Aliases, YAML frontmatter, callouts, and task syntax
- Duplicate filenames and automatic renaming
- Whether an import can be undone or repeated into a clean workspace
If the documentation is silent about a feature, treat that feature as unverified rather than assuming it will work.
Step 4: Decide whether to convert Wikilinks
Obsidian’s own documentation identifies Markdown links as an interoperability option. Converting [[Note]] to a Markdown link can help an app that parses ordinary Markdown but does not recognize Wikilinks. Conversion is not automatically safer, however: a tool must choose the correct path, preserve meaningful display text, and handle headings, aliases, and block references.
Rank #3
- Slim durable design to help take your important files with you
- Vast capacities up to 6TB[1] to store your photos, videos, music, important documents and more
- Back up smarter with included device management software[2] with defense against ransomware
- Help secure your important files with password protection and hardware encryption
- 3-year limited warranty
Use the destination’s importer when it explicitly supports Obsidian syntax. Otherwise, convert a copy of the vault, never the untouched backup, and inspect the resulting links before import.
- Preserve the visible link label when it carries meaning; do not replace a descriptive label with a raw filename.
- Keep the target’s folder path and filename exactly as they are during conversion.
- Encode spaces in Markdown destinations as
%20when required by the destination’s parser. - Do not claim that a converted block reference is equivalent to the original block. A block identifier may have no supported target in the new app.
- Save the converted files in a separate staging folder so you can compare them with the originals.
Step 5: Copy notes and attachments together
Copy the Markdown files and their referenced files as one path-preserving set. Avoid renaming, deduplicating, or reorganizing during this first transfer; every extra change makes a broken link harder to diagnose.
- Recreate the vault’s top-level and nested folders in the staging area, or copy the complete folder tree in one operation.
- Copy all
.mdfiles without changing their filenames or extensions. - Copy every attachment folder and every file referenced by an embed or ordinary file link.
- Retain capitalization, punctuation, spaces, and file extensions. Some operating systems are case-insensitive while destination parsers are not.
- Include files stored beside notes as well as files in a common attachment folder.
- Do not delete apparently unused files until the migration has been validated; a reference may be generated by a plugin or hidden in a less obvious note.
Obsidian’s attachment settings can place a dragged file in a vault folder, a specified folder, the same folder as the current note, or a subfolder under the current folder. That is why a notes-only export is unsafe: the location is configurable, not fixed.
Step 6: Run a representative sample import
Do not begin with the whole vault. Create a small test set that exercises the structures most likely to fail, and import it into a clean destination workspace.
Include at least:
- A normal note-to-note link.
- A link whose filename contains spaces.
- A link to a note in a nested folder.
- A heading link.
- A block reference.
- An alias or custom display label.
- An inline image and an image stored in a nested attachment path.
- A PDF or another non-image file embed.
- A note with frontmatter, callouts, and task items if your vault uses them.
- Two notes with similar or duplicate filenames, if those exist in the vault.
For each sample, test the result rather than merely reading the imported Markdown:
Free tools Windows power users keep installed
One-click scans. No signup required.
Rank #4
- High-capacity external hard drive with up to 2TB of storage The ModusTech Facet portable external hard drive gives you dependable HDD storage in a slim 2.5-inch design. Multiple capacities available up to 2TB — back up photos, videos, music, documents, and game libraries with room to grow. A trusted external storage solution for everyday backup, media archives, and creative work.
- USB-C and USB 3.1 connectivity with included 2-in-1 cable The Facet ships with a USB-C to USB-C cable and tethered USB-A adapter, so this external hard drive connects to modern laptops, USB-C iPhones, tablets, and older USB-A computers without buying an extra cable. USB 3.1 Gen 1 (5Gbps) interface delivers real-world transfer speeds up to 100MB/s — fast enough to back up 50GB of files in about 8 minutes.
- Plug-and-play external hard drive for PC, Mac, and laptops Preformatted in exFAT and ready to use the moment you plug it in. The Facet works out of the box with Windows PCs, macOS Macs, MacBooks, Chromebooks, and laptops — no drivers, no software, no setup required. A true plug-and-play external hard drive built for everyday use across every major operating system.
- External hard drive for PS4, Xbox One, and Smart TV gaming The Facet is compatible with PlayStation 4, Xbox One, and Smart TVs with USB support. PS4 and Xbox One games run directly from the drive — plug it in, format through the console, and add to your storage. Also works with Smart TVs that support USB recording or external media playback.
- Slim, shock-resistant portable external hard drive — 160g At 2.5 inches and just 160g, this portable external hard drive is bus-powered through a single USB-C cable — no separate power adapter, no extra cables. Slim enough for a laptop bag, jacket pocket, or camera bag, with a shockresistant casing and faceted diamond-texture top panel that resists fingerprints and everyday wear. Backed by a 1-year limited warranty from ModusTech, a consumer electronics brand specializing in external storage.
- Open the note in the destination.
- Activate each internal link and confirm that it opens the intended note.
- Follow heading and alias links and check that the target location is correct.
- Inspect block references and record whether they remain usable, become plain text, or disappear.
- Confirm that images render inline at the intended size or position.
- Open PDFs and other linked files, not just their filenames.
- Check that paths containing spaces and nested folders resolve.
- Compare important frontmatter and metadata with the source note.
If a sample fails, stop and adjust the conversion or folder layout before importing more notes. A successful import of ordinary links does not prove that advanced constructs work.
Step 7: Import the full vault and validate it
After the sample passes, import the remaining notes using the same path and conversion rules. Keep the source backup untouched while the destination is being populated.
Use a post-import checklist:
- Search for unresolved-link indicators supplied by the destination.
- Search the imported text for remaining Wikilinks if the destination is supposed to contain only Markdown links.
- Check for references to files that were not copied.
- Open a selection of older notes, recently edited notes, and notes in every major folder.
- Inspect image, PDF, audio, and video embeds.
- Review notes containing block references, aliases, callouts, and plugin-created fields.
- Look for duplicate filenames that may have been renamed on import.
- Compare a few representative files byte-for-byte or line-by-line with the staging copy when exact text matters.
Keep a list of exceptions instead of silently accepting them. For each unsupported feature, record the original syntax, the imported result, and whether you will manually repair it, retain the original note elsewhere, or leave it as plain text.
Independent reader supportYour contribution helps us test, update, and keep practical guides available for everyone.Common failures and how to recover
Links open nothing
Check whether the destination expects Wikilinks or Markdown, whether the .md extension is required, and whether the folder path is relative to the note or to an application root. Restore the original folder structure in a clean test workspace and retest one failing link before changing every note.
Images or PDFs are missing
Compare the path written in the note with the actual copied filename, including capitalization, spaces, and extension. Confirm that the attachment folder was included in the transfer and that the destination importer did not move notes without their referenced files.
Best Value
- Slim durable design to help take your important files with you
- Back up smarter with included device management software[2] with defense against ransomware
- Help secure your important files with password protection and hardware encryption
- 3-year limited warranty
Only some duplicate-name links fail
Shortest-path links can become ambiguous when two folders contain similarly named notes. Preserve full folders, then convert the affected links to explicit relative or destination-supported paths. Do not rename files globally until you have a second backup.
Heading links land at the wrong place
Heading anchors are generated differently by Markdown parsers. Check punctuation, capitalization, duplicate headings, and the destination’s anchor rules. A heading link that opens the note but not the intended section is still a migration defect.
Block references become plain text
Obsidian block references are app-specific rather than standard Markdown. Export the referenced text into a normal heading or paragraph, or recreate the relationship using the destination’s own supported feature. Keep the original note available so you can identify what the block pointed to.
Links work in the sample but fail after bulk import
Look for an importer rule that renames duplicates, flattens folders, changes case, or relocates attachments. Compare the sample workspace and full workspace directory trees, then rerun the import into a clean destination after correcting the cause.
Rollback and long-term cleanup
Rollback is straightforward when the source backup remains untouched: remove or archive the failed destination workspace, restore from the backup, correct one migration variable, and repeat the sample test. Do not “repair” the only original copy in place.
Once the destination has passed link and attachment checks, keep at least one archival copy of the original vault. You can then reorganize folders, rename notes, or remove obsolete files in the new app as a separate project. Make a fresh backup before each large cleanup because automatic link updating in one application does not guarantee that another application can follow the resulting paths.
Migration checklist
- Complete vault copied or zipped before edits.
- Markdown notes and every attachment copied together.
- Folder structure, filenames, capitalization, and extensions preserved.
- Destination importer and supported syntax confirmed.
- Wikilink conversion performed only on a staging copy, if needed.
- Sample includes ordinary links, spaces, nested paths, headings, blocks, aliases, images, and PDFs.
- Links opened their intended targets in the destination.
- Embedded files rendered and opened.
- Unsupported constructs documented and manually handled.
- Untouched source backup retained after the migration.
What “successful” means
A migration is complete when the destination contains the notes and referenced files, ordinary links open the intended notes, embeds render, and you have explicitly accounted for features the destination cannot represent. A syntactically valid Markdown file is not proof that its attachments exist or that an Obsidian-specific reference survived. Treat the destination’s observed behavior—not the file extension—as the final test.
The Tool Desk
Outbyte PC Repair FREERepair Windows errors before they cause bigger problemsFix Now →Outbyte Driver Updater FREEScan for outdated or missing drivers - takes under a minuteDriver Scan →Quick Recap
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
