OneDrive migration guide: same tenant and cross-tenant
How OneDrive sites are found and provisioned, which permission the lookup needs, what Microsoft's native cross-tenant move does and does not do, and a step-by-step plan.
OneDrive looks like the simplest workload in a Microsoft 365 migration and hides the most moving parts per user. Every account is its own SharePoint site collection with its own URL, provisioning state, storage quota, sharing links and version history, and a cross-tenant OneDrive migration multiplies that by every person in the organisation. This guide explains how a OneDrive is located and created, which permission the lookup needs, what Microsoft's native cross-tenant move does and does not do, what carries through the Migration API, and how to run the project so people keep working until the last day.
What a OneDrive actually is
A user's OneDrive is a personal site collection under https://{tenant}-my.sharepoint.com/personal/{upn-mangled}, where the UPN has its dots and at-sign replaced with underscores. Files live in that site's Documents library. Everything that applies to a SharePoint library applies here: the 400-character path limit, invalid characters, the 250 GB per-file limit, version history and unique permissions. The differences are practical: the site may not exist yet, its URL cannot be assumed from the UPN when a user has been renamed, and the library uses the OneDrive template (700), which rejects the generic 0x0101 document content type and needs the library's own Document content type id on import.
Finding the site therefore needs a lookup, not string manipulation. SharePoint's PeopleManager returns the exact PersonalUrl for an account name, and that call needs the SharePoint User.Read.All application permission in addition to Sites.FullControl.All. Without it the migration cannot resolve a single OneDrive, which is the commonest permission gap in OneDrive projects.
Provisioning the destination OneDrive
In a cross-tenant migration most destination users have never opened OneDrive, so the personal site does not exist. The Migration API needs a real destination web, so the site has to be created first. SharePoint exposes a bulk enqueue for this: ProfileLoader.CreatePersonalSiteEnqueueBulk takes a list of UPNs and queues provisioning; the migration then polls PeopleManager until the URL appears.
- ShareShift resolves the URL, enqueues provisioning if it is empty, and polls every 15 seconds for up to five minutes by default before reporting that provisioning did not complete in time.
- Provisioning is asynchronous on Microsoft's side; for a large user population, pre-provision in bulk days ahead so the migration itself never waits.
- The destination user must be licensed for OneDrive; an unlicensed account has nothing to provision.
- If the source user has been renamed, look the source OneDrive up by the current UPN, not the historical one.
Microsoft's native cross-tenant OneDrive migration
Before buying a tool, check whether Microsoft's own cross-tenant OneDrive migration fits, because for a straightforward one-shot move it is designed for exactly this. It is PowerShell driven, leaves a redirect at the old URL so links keep working, and is available to any customer with the per-user Cross-tenant User Data Migration licence. Microsoft does not publish that licence's price; reseller listings suggest roughly US$15 per user, which could not be verified. Migration Orchestrator, in public preview since 22 December 2025, wraps the same OneDrive move in a wizard together with mailboxes, chats and meetings.
| Native cross-tenant OneDrive move | Detail |
|---|---|
| Mode | One-and-done, with redirect |
| Incremental or delta passes | None. After the move, nothing further is synchronised. |
| Queue | Up to 4,000 queued |
| Per-site limits | 5 TB or 1 million items |
| Pre-existing destination | Destination sites must not pre-exist |
| Licence | Cross-tenant User Data Migration, per user |
| Not included | Teams channels and structure; SharePoint sites for non-EA customers; workflows and Power Platform |
The constraint that pushes projects to a third-party tool is the absence of delta. With the native move a user's OneDrive is frozen and moved in one step, so every user needs an outage window and there is no pilot pass that can be refreshed. A tool copying through the Migration API can run a bulk pass while people keep working, then incremental passes up to cutover. The choice is a trade between free with an outage per user and paid with no outage, and for small user counts the native route can be the right answer; the tenant to tenant guide sets out how to combine the two.
What carries through the Migration API
| Item | Result |
|---|---|
| Files and folders | Migrated, with the destination landing folder created beforehand if used |
| Version history | Full history, nested oldest first so every version and its timestamp survive; incremental updates add a version on top rather than replacing the file |
| Created, Modified, Author, Editor | Set from the source where the user maps to a destination UPN; unresolved users fall back to a nominated account and are reported. The file-level modified-by property stays as the app; the item Editor and both Author fields are restored |
| Unique permissions | Broken-inheritance permissions on folders and files copied after import, with users mapped and groups matched by name |
| Sharing links | Only where the API allows; treat anonymous and organisation links as needing re-creation |
| Recycle bin, sync state, Known Folder Move | Not migrated; the user re-syncs the new location |
Because OneDrive content is personal, the mapping is per person rather than per site. A CSV of source to destination UPNs, plus domain rewrites for the common case where only the suffix changes, covers it. Mapped users are verified at the destination before import so authorship is real, and anyone who cannot be resolved is listed in the report rather than silently replaced.
Step-by-step plan
- Inventory. List every source OneDrive with its size, item count and owner status (active, disabled, departed). Departed users' OneDrives usually need a decision: migrate to a manager's OneDrive, to a SharePoint archive library, or not at all.
- Assess. Run the assessment for path length against the destination URL, invalid characters, large files and blocked types. OneDrive paths are long already because of the personal site prefix.
- Licence and provision. Confirm every destination user has a OneDrive licence, then bulk enqueue provisioning days ahead.
- App registrations. One in each tenant with SharePoint
Sites.FullControl.AllandUser.Read.Allas application permissions and a certificate credential. Microsoft requires app-only authentication for migration traffic and throttles certificate credentials less than secrets. Allow about five minutes after consent before tokens carry the roles. - Pilot. Migrate a few volunteers end to end. Check versions, dates and a shared folder, and have them sync the new location.
- Bulk pass. Run everyone while they keep working, off-peak where possible, because Microsoft's limits are tighter for background apps during weekday daytime.
- Incremental passes. Re-run to pick up changes; unchanged files are skipped, changed ones become new versions. Choose a conflict rule for files edited at both ends.
- Cutover. Per user or per wave: stop sync on the old tenant, run a final incremental pass, and have the user sign in and sync the new OneDrive. Communicate that sharing links need re-sharing.
- Report and close. Export the item-level report and completion record per user or per wave; see the completion report article.
OneDrive to SharePoint and same-tenant moves
Two other OneDrive scenarios use the same machinery. Moving a departed user's OneDrive into a SharePoint library preserves the content and its history under team ownership rather than under a licence that is about to lapse; the source is the personal site's Documents library and the destination is any library. And consolidating content from OneDrive into team sites during a restructure is a library to library copy with a landing folder.
For file-heavy OneDrive work, ShareShift uses the Migration API with encrypted packages uploaded from your own worker, so content never passes through our servers, and every step is checkpointed so a stopped run resumes without re-uploading. The ShareGate comparison page sets out where the two tools differ on OneDrive, and the pricing page has the Monthly, Annual and MSP plans and the 30-day trial.
Frequently asked questions
Does OneDrive migration keep version history?
Yes, through the Migration API when the tool nests the full history under each file, oldest first. Emitting one object per version makes SharePoint delete and recreate the item so only the last version survives, which is a tool implementation detail worth asking about.
Which permission does a OneDrive migration need?
SharePoint Sites.FullControl.All as an application permission for the Migration API, plus SharePoint User.Read.All to look up a user's OneDrive URL through PeopleManager and to ensure the personal site exists. Both need admin consent and a certificate credential.
Can Microsoft migrate OneDrive between tenants for free?
The tooling is free but each user needs the Cross-tenant User Data Migration licence, whose price Microsoft does not publish. The move is one-and-done with a redirect and no delta pass, up to 4,000 queued and 5 TB or 1 million items per site.
What happens if the destination OneDrive does not exist?
It must be provisioned before import. The tool enqueues provisioning through SharePoint's profile loader and polls for the personal URL; ShareShift waits up to five minutes by default. For large populations, pre-provision in bulk ahead of the migration.
Run your first migration on a 30-day free trial
Every workload, unlimited data, three workers, pause and resume built in. Worker-only, so your content never passes through our servers. The trial key is issued from the portal and works with the same app you would buy.