Microsoft 365 cross-tenant OneDrive migration (tenant-to-tenant): the complete step-by-step guide to move user data without losing control

Quick summary: cross-tenant OneDrive migration in 10 points

1. Define the scenario: merger (M&A), carve-out, domain change, reorg, tenant consolidation, or partner change.
2. Decide the scope: which users migrate, what happens to ex-employee OneDrives, and what content is archived instead of migrated.
3. Design identity: target UPN/domains, guest strategy (B2B), and user/group mapping to preserve permissions.
4. License CTUDM: validate and procure Cross-Tenant User Data Migration (required for the native approach).
5. Prereqs that can block you: Customer Key in the source, OneDrive in read-only, OneDrive already created in the target, active legal holds, path/volume limits.
6. Prepare “identity mapping”: the CSV that links source and target identities (users/groups and URLs) to preserve permissions.
7. Establish trust: cross-tenant relationship via PowerShell (source & target) and verification.
8. Migrate in waves: planned batches and windows (up to 4,000 OneDrives queued per batch), monitoring, and retries when failures occur.
9. Manage the user experience: sync client (OneDrive Sync), redirects, shared links, communications, and post go-live support.
10. Close with governance: access recertification, guest cleanup, Purview policies in the target, and a backup/recovery plan.

Context note: moving files is only one part. Success typically depends on identity, permissions, links, adoption, and compliance.

When do you need to migrate OneDrive between Microsoft 365 tenants?

A cross-tenant OneDrive migration typically comes up when the client’s structure, brand, or operational scope changes. OneDrive is each user’s “personal work space”: drafts, work-in-progress documentation, deliverables, notes, and files shared via links. If it’s moved poorly, the experience is simple: “information is missing” and “things broke.”

Common scenarios

• Mergers and acquisitions (M&A): two organizations with separate tenants need to consolidate people and files.
• Carve-out / spin-off: part of the business separates and needs its own tenant, moving only a subset of users.
• Rebrand / domain change: identity is normalized and UPN/email addresses are reorganized, directly impacting OneDrive.
• Consolidating historical tenants: multiple legacy tenants are unified to simplify governance and licensing.
• International reorganization: changes by country/region or adopting Multi-Geo in the target.

Section recap: when the user changes “home” (tenant), OneDrive must move too. The key is preserving permissions, links, and a transition users can understand.

Introduction: what really changes when moving OneDrive to another tenant

In a Microsoft 365 cross-tenant OneDrive migration, it’s not just about copying files. You’re moving a workspace connected to identity, device synchronization, external sharing, and—in many cases—compliance (retention, eDiscovery, auditing).

That’s why a serious plan answers practical questions:

• Which OneDrives migrate? (active users, relevant externals, leavers’ accounts—shared mailboxes don’t apply—special accounts).
• What happens to shared links? (internal, external, “anyone with the link,” old links embedded in emails).
• How is access preserved? (mapping users/groups and recertifying permissions in the target).
• What does the “day after” look like? (OneDrive Sync, Teams, Office, favorites, local paths, mobile).

One advantage of the native cross-tenant approach is that it places redirects in the original OneDrive so links can continue working, and the typical impact is reduced to a brief window where the source OneDrive becomes read-only.

Section recap: the migration is technical and operational: users must find their files, links must not “die,” and security/compliance should stay the same—or improve.

1. Methodology and project governance (waves, pilot, roles)

In practice: OneDrive migrates best in waves. A representative pilot prevents surprises and helps fine-tune communications, mappings, and support.

1.1 Recommended wave-based approach

1. Pilot: 10–30 representative users (different profiles, volumes, and sharing patterns).
2. Progressive waves: by department, location, or criticality (sales, finance, operations, etc.).
3. Cutover and stabilization: reinforced support, validations, and final adjustments (permissions, guests, DLP).

1.2 Typical roles (simplified RACI)

One decision that reduces incidents significantly: agreeing on what “done” means for each wave (for example, OneDrive Sync checked, access to critical shared folders validated, and critical tickets closed).

Section recap: waves create control. “All at once” saturates support and turns small issues into major disruption.

2. Assessment: inventory, dependencies, and common “blockers”

In practice: assessment prevents predictable failures (holds, long paths, OneDrive already created in target, etc.).

2.1 Minimum inventory worth collecting

• Users to migrate: active users, relevant externals, leavers (decide archive vs migrate).
• Volume per user: size, item count, sharing patterns (internal/external).
• Long paths: legacy structures with deep nesting (a real failure risk).
• Compliance controls: retention/holds/eDiscovery and existing DLP policies.
• Devices: how many use OneDrive Sync, how many are shared devices or restricted endpoints.

2.2 Frequent blockers to detect early

• Target OneDrive already created: if it exists, the native migration can’t overwrite it.
• Legal holds: OneDrive under a hold becomes blocked for migration.
• Customer Key (service encryption): if enabled in the source tenant, the migration fails.
• Paths beyond limits: deep structures + longer target URLs can break the move.

A very practical decision to make early: what happens to OneDrive data for users who are no longer employed. In M&A or carve-outs, it’s common to find OneDrives containing critical process content. Typical approaches include:

• Reassign ownership or recover the content into a SharePoint site (team repository) before migration.
• Migrate the OneDrive but assign a content owner/manager in the target (and review sharing permissions).
• Archive (export or backup) if required, without keeping it as an active OneDrive.

Section recap: assessment isn’t bureaucracy—it’s how you avoid known failure modes and decide what to do with “orphaned” content.

3. Identity and mapping strategy: UPN, domains, and groups

In practice: if user identity changes, permissions and sharing depend on a correctly designed mapping.

3.1 Typical identity decisions

• Will the primary domain remain the same? (e.g., company.com) or will a new one be adopted?
• What will UPNs look like? (same alias, new alias, temporary coexistence).
• Which groups “live” in Entra/M365? and how they are recreated in the target (member/owner mapping).

3.2 Guests and external collaboration

OneDrive is widely used for sharing with third parties. Before migrating, it’s useful to classify:

• Stable collaboration: recurring vendors/customers (managed guests with periodic review).
• Occasional collaboration: expiring links and “specific people” access when feasible.
• Historical links: older links in emails/chats (risk of becoming “blind spots” without governance).

The native approach can preserve permissions when users and groups are included in the mapping file. That’s why identity mapping must be treated as a critical project artifact, not “just another CSV.”

Section recap: OneDrive migration won’t hold together if identity and groups are not organized. Content may arrive, but access and links can become inconsistent.

4. CTUDM licensing and approach decisions (native vs third-party)

In practice: the native approach requires CTUDM. If this isn’t decided early, the project stalls at the worst possible time.

4.1 CTUDM (Cross-Tenant User Data Migration)

With Microsoft’s native method, cross-tenant OneDrive migration requires CTUDM licenses per migrated user (a one-time fee per migration). These licenses can also cover cross-tenant mailbox migration when included in the same program.

4.2 When should you consider third-party tools?

While the native method is strong, third-party tools can help in certain scenarios:

• Need for more detailed reporting (per file, per error, per retry) and executive dashboards.
• Cases requiring more guided orchestration (discovery, mapping, waves, retries).
• Specific requirements (for example, tailored sharing strategies or transformations).

Section recap: “native vs third-party” isn’t about preference—it’s about scope, reporting, requirements, and internal operational capacity.

5. Technical prerequisites to validate before migrating OneDrive between tenants

In practice: many failures happen because prerequisites are ignored. Validating first reduces retries and wasted change windows.

5.1 Baseline prerequisites

• Have SharePoint Online PowerShell up to date.
• Validate the source OneDrive is in Read/Write (read-only causes failures).
• Ensure OneDrive is not already created in the target for those users (it cannot be overwritten).

5.2 Blocking prerequisites (and how to handle them)

• Customer Key in the source: if enabled, migration fails. Plan handling with security/compliance.
• Active legal holds: OneDrive with a hold is blocked; remove hold, migrate, reapply in the target as appropriate.
• Unsupported environments: cross-tenant OneDrive migration isn’t available in certain sovereign/government clouds.

5.3 The “small detail” that causes big failures: paths and URLs

In real projects, a common failure driver is a combination of:

• Legacy folders with deep nesting.
• Very long folder names (years, versions, descriptions, etc.).
• A target OneDrive URL longer than expected (for example, due to naming conventions).

The result: paths exceeding the allowed limit. The fix is typically practical: shorten the structure in the source before moving, and keep target URLs reasonably short.

Section recap: prerequisites and limits are part of design. Ignoring them turns the project into “retry and hope.”

6. Pre-create users/groups and prevent OneDrive from being created in the target tenant

In practice: if the user signs into the target and OneDrive is provisioned too early, the native migration can fail.

6.1 Pre-create identity and licenses in the target

• Create target users and groups identified for migration (including groups used in permissions).
• Assign required licenses (OneDrive/SharePoint per plan and CTUDM if applicable).

6.2 Restrict OneDrive provisioning during the project

During a cross-tenant migration, it’s often advisable to restrict OneDrive provisioning in the target to prevent sites from being created before the move. If OneDrive already exists in the target, the process can’t overwrite it.

In coexistence projects (users still working in the source tenant), it can also be necessary to restrict new OneDrive provisioning in the source to avoid new “out-of-plan” content appearing (especially when migrating by waves).

Section recap: pre-creating is required—but pre-creating “too much” (provisioning OneDrive too early) can break the migration. Timing must be controlled.

7. Identity mapping in cross-tenant OneDrive migration: CSV, URLs, and rules to preserve permissions

In practice: the mapping file is the “who is who” translation between tenants. If it fails, permissions and access degrade.

7.1 What mapping must reflect

• Relationship between source UPN and target UPN.
• Relationship between source and target OneDrive URLs.
• Inclusion of relevant users and groups required to preserve permissions in the target.

7.2 CSV example (simplified to explain the logic)

SourceUserPrincipalName,TargetUserPrincipalName,SourceOneDriveUrl,TargetOneDriveUrl
ana.perez@source.com,ana.perez@target.com,https://source-my.sharepoint.com/personal/ana_perez_source_com,https://target-my.sharepoint.com/personal/ana_perez_target_com
juan.garcia@source.com,juan.garcia@target.com,https://source-my.sharepoint.com/personal/juan_garcia_source_com,https://target-my.sharepoint.com/personal/juan_garcia_target_com

In real projects, mapping typically includes groups and special cases. Treat the CSV as a controlled deliverable: version it (internal repo), review it with IT and security, and use it as the single source of truth throughout execution.

7.3 Practical rules that prevent errors

• Normalize UPNs: avoid “similar-but-not-equal” variants (temporary domains, inconsistent aliases, etc.).
• Keep URLs clean and short: reduce long-path risk and avoid problematic characters.
• Include groups used in permissions: if a group isn’t mapped, permissions may not rebuild as expected.

Section recap: if the client wants to preserve permissions and traceability, mapping is the central piece. Without it, content arrives but access becomes unpredictable.

8. Establishing trust between tenants for OneDrive migration (Set-SPOCrossTenantRelationship)

In practice: the trust relationship is set up in both tenants. It’s not always a “one-and-done” step if Multi-Geo or multiple destinations are involved.

Cross-tenant migration relies on creating a relationship between the source and the target tenant. Operationally: the move is authorized and the migration “partner” is defined.

8.1 Typical commands (illustrative)

# SOURCE tenant
Connect-SPOService -Url https://source-admin.sharepoint.com

# Send trust request to TARGET
Set-SPOCrossTenantRelationship -Scenario MnA `
  -PartnerRole Target `
  -PartnerCrossTenantHostUrl "https://target-my.sharepoint.com"

# TARGET tenant
Connect-SPOService -Url https://target-admin.sharepoint.com

# Send trust request to SOURCE
Set-SPOCrossTenantRelationship -Scenario MnA `
  -PartnerRole Source `
  -PartnerCrossTenantHostUrl "https://source-my.sharepoint.com"

Projects typically include a follow-up verification step to confirm trust is ready before scheduling waves. In Multi-Geo environments, configuration must be repeated where required (and it’s essential to document which instance trusts which).

Section recap: trust is the “bridge” between tenants. If it’s not correctly established (and verified), waves fail or get blocked.

9. Starting a cross-tenant OneDrive migration: Start-SPOCrossTenantUserContentMove (wave-based execution)

In practice: you schedule in batches, control the queue, and migrate with monitoring. Wave planning matters more than the “start” command.

9.1 Before launching a wave

• Confirm compatibility status (compatible or warning depending on environment criteria).
• Validate the user exists in the target with the right licenses and without a pre-provisioned OneDrive.
• Confirm the user isn’t blocked by a legal hold.

9.2 Execute the move per user (or in a controlled series)

# In the SOURCE tenant
Connect-SPOService -Url https://source-admin.sharepoint.com

Start-SPOCrossTenantUserContentMove `
  -SourceUserPrincipalName ana.perez@source.com `
  -TargetUserPrincipalName ana.perez@target.com `
  -TargetCrossTenantHostUrl https://target-my.sharepoint.com/

9.3 Scheduling within a window (when timing must be controlled)

When the client needs the move to start in a specific time window (for example, after hours), it can be scheduled using UTC date parameters. This is especially useful for large waves or critical users with dedicated support.

Start-SPOCrossTenantUserContentMove `
  -SourceUserPrincipalName juan.garcia@source.com `
  -TargetUserPrincipalName juan.garcia@target.com `
  -TargetCrossTenantHostUrl https://target-my.sharepoint.com/ `
  -PreferredMoveBeginDate "2026-01-12T20:00:00Z" `
  -PreferredMoveEndDate   "2026-01-12T23:30:00Z"

Section recap: “start” isn’t the project. The point is that each wave is explainable, measurable, and supportable—with controlled impact.

10. Monitoring, cancellation, states, and common errors

In practice: monitoring enables decisions: proceed, reschedule, or stop a specific case before it impacts more users.

10.1 Check migration status

# Can be executed in SOURCE or TARGET
Get-SPOCrossTenantUserContentMoveState `
  -PartnerCrossTenantHostURL https://target-my.sharepoint.com/

In real operations, it’s helpful to filter by user for wave support (especially when tickets come in):

Get-SPOCrossTenantUserContentMoveState `
  -PartnerCrossTenantHostURL https://target-my.sharepoint.com/ `
  -SourceUserPrincipalName ana.perez@source.com -Verbose

10.2 Cancel (when still possible)

Stop-SPOCrossTenantUserContentMove -SourceUserPrincipalName ana.perez@source.com

10.3 Common errors and mitigation

• OneDrive already exists in the target: restrict provisioning early and validate per user.
• Legal hold applied: remove hold, migrate, reapply per policy in the target.
• Excess size or item count: clean/archive or split content (and document the decision).
• Paths too long: shorten structure, rename folders, reduce depth before migrating.
• Link/external access issues: strengthen guest policy and review “who had access” after the move.

Section recap: without monitoring, you end up with “it migrated, but nobody knows what happened.” Monitoring enables prioritization and clear answers.

11. User experience: OneDrive Sync, redirects, and post-change support

In practice: users don’t ask about PowerShell—they ask about folders, sync, and whether links still work.

11.1 What users typically notice

• A short window where the source OneDrive may become read-only.
• After completion, OneDrive “lives” in the target tenant and the source has a redirect.
• On devices using OneDrive Sync, users may need to sign in again or re-sync.

11.2 Communication that reduces tickets

Simple wave-based communication works well (no jargon), with three sections:

• What will happen: “your OneDrive will move to the new tenant and redirects will remain in place.”
• What to do: “if sync pauses or prompts for credentials, follow the internal procedure.”
• What not to do: “don’t create mirrored folders, don’t duplicate data, don’t re-upload what already exists.”

11.3 Post-migration support (first 5–10 days)

Support should be ready for typical incidents:

• Sync conflicts (files in use, long paths, invalid characters).
• Shared folders “disappearing” until the user re-authenticates.
• External (guest) access requiring revalidation due to target policies.

Section recap: the technical move can be perfect and still feel chaotic if sync and sharing aren’t guided.

12. Sharing and links after migrating OneDrive between tenants: what is preserved and how to avoid losing control

In practice: the most sensitive part of OneDrive is shared links (especially external) and user shortcuts/access patterns.

12.1 Shared links and redirects

One key advantage of cross-tenant migration is that once completed, a redirect is placed at the source OneDrive location so older links can continue directing to the new destination (as long as the accessing party still has permissions in the target).

12.2 Permissions: why mapping matters so much

When users and groups are included in identity mapping, permissions related to the migrated OneDrive are preserved in the target. If an identity (user or group) is missing from mapping, that permission can be lost or become a manual remediation case.

12.3 Third-party collaboration (customers/vendors)

In environments with heavy external sharing, two practices help:

• Catalog “sensitive shares” (folders with critical data) and validate them post-migration with the process owner.
• Apply target rules (link expiration, “specific people,” periodic guest reviews) to ensure the migration doesn’t expand risk.

Section recap: the goal isn’t “everything stays exactly the same,” but that collaboration keeps working and is better governed in the target tenant.

13. Compliance and security for OneDrive migration: Purview, retention, holds, and auditing

In practice: if the client is audited (or wants to be), the migration must close with clear retention, classification, and evidence.

13.1 Sensitivity and information protection

After migrating, it’s the right moment to ensure the target tenant applies a coherent classification and protection policy. Sensitivity labels help keep a file controlled even outside the browser, depending on the defined policy.

13.2 Retention, disposition, and eDiscovery

Retention isn’t an “add-on”; it’s a business and compliance decision: how long each category of information is kept and how it’s disposed of. OneDrive includes personal work content and also “process” content that never should have lived there. A migration is an opportunity to organize:

• Operational content that should live in SharePoint (team repository).
• Personal work content that must be retained and migrated.
• Content that must be archived due to legal requirements or internal policy.

13.3 Legal holds

If a OneDrive has a hold applied, cross-tenant migration can be blocked. This requires coordination with legal/compliance: remove the hold to migrate, and reapply it in the target in a controlled way.

Section recap: a “compliant” migration isn’t measured only in gigabytes moved. It’s measured by control, traceability, and audit readiness.

14. Limits and considerations that affect cross-tenant OneDrive migration

In practice: limits aren’t theoretical—they’re the reason for many failures and reschedules if not addressed early.

14.1 Common limits worth reviewing

• Size and item count: large OneDrives or too many items can fail when limits are exceeded.
• Long paths: deep structures can exceed maximum supported character counts.
• Batch queue: up to 4,000 migrations scheduled per batch; for more users, split into waves.

14.2 Multi-Geo

In Multi-Geo environments, planning is more demanding: define the correct target geo per region, load mappings where required, and ensure trust relationships across the involved instances. Without documentation, operations become hard to run.

14.3 An important point: “one-and-done”

Cross-tenant OneDrive migration is designed as a one-time move: the content is moved and a redirect remains in the source. This makes timing critical for each wave: it’s not designed for incremental “pre-stage + delta” passes like in other technologies.

Section recap: limits and “one-and-done” shape the plan. Mitigation is waves, pre-cleanup, and controlling OneDrive provisioning in the target.

15. Backup and recovery for a cross-tenant OneDrive migration: a practical approach

In practice: “resilience” isn’t the same as “recovery.” Decide how you restore if something goes wrong or critical content is deleted.

15.1 Scenarios worth covering

• Accidental deletion: folders deleted by mistake before or after the move.
• Ransomware / encryption from a compromised account: spread to synced folders.
• Unwanted overwrites: users replacing versions without realizing.
• Permission/sharing errors: unintended exposure or loss of access.

15.2 How to approach it without complicating operations

A reasonable approach combines:

• Native controls (recycle bin, versioning, auditing) as a “first response.”
• A defined restore process with roles, timings, and evidence (who restores, how, and when).
• If required, an additional backup solution (for example, Microsoft 365 Backup capabilities or third-party solutions), with periodic recovery testing.

Section recap: migrations finish well when there is a tested recovery plan and clear accountability—not when “nothing happened.”

16. Tools and methods for cross-tenant OneDrive migration: native vs third-party (a realistic comparison)

In practice: tool choice should match requirements and operational capacity—not “the one always used.”

In mid-to-large projects, a hybrid model is common: the native approach for the main move plus complementary tools for inventory, reporting, or special cases. What matters is that the result is verifiable and defensible to business and security.

Section recap: the best method is the one the client can operate with control, support, and evidence—not the one that “looks fastest” on paper.

17. Operational checklists (pre, during, post) for cross-tenant OneDrive migration

17.1 Before migrating

• CTUDM purchased and assigned (if using the native approach).
• Prereqs validated (holds, Customer Key, target OneDrive, Read/Write, limits).
• Users and groups pre-created in the target and licenses assigned.
• Restrict OneDrive provisioning in the target during the project.
• Identity mapping (CSV) reviewed and versioned.
• Wave-based comms plan + reinforced support plan.

17.2 During migration

• Run waves in defined windows (if required) and monitor status.
• Handle per-user failures and resolve root causes (paths, existing OneDrive, hold).
• Communicate progress with simple metrics (success / failed / rescheduled).

17.3 After migration

• Validate access to target OneDrive and re-sync (OneDrive Sync).
• Review external sharing and guests (cleanup and recertification).
• Apply or adjust Purview (sensitivity, retention, DLP) in the target.
• Close with evidence: wave report, incidents, and corrective actions.

Section recap: checklists turn the migration into a repeatable process. Without them, each wave is run “from memory.”

18. Useful scripts and snippets (PowerShell/CSV) for cross-tenant OneDrive migration

In practice: these commands save time on repetitive tasks, but they don’t replace design and mapping.

# Source
Connect-SPOService -Url https://source-admin.sharepoint.com

# Target
Connect-SPOService -Url https://target-admin.sharepoint.com

Get-SPOCrossTenantCompatibilityStatus -PartnerCrossTenantHostURL https://target-my.sharepoint.com/

Get-SPOCrossTenantUserContentMoveState -PartnerCrossTenantHostURL https://target-my.sharepoint.com/

Start-SPOCrossTenantUserContentMove `
  -SourceUserPrincipalName ana.perez@source.com `
  -TargetUserPrincipalName ana.perez@target.com `
  -TargetCrossTenantHostUrl https://target-my.sharepoint.com/

SourceUserPrincipalName,TargetUserPrincipalName,SourceOneDriveUrl,TargetOneDriveUrl
ana.perez@source.com,ana.perez@target.com,https://source-my.sharepoint.com/personal/ana_perez_source_com,https://target-my.sharepoint.com/personal/ana_perez_target_com

Section recap: scripts help operations, but project order (prereqs, mapping, waves, support) remains the determining factor.

19. Frequently asked questions (expanded FAQ) about cross-tenant OneDrive migration

20. Official resources and recommended links

• Cross-tenant OneDrive migration (overview)
• Step 1: Connect to source and target tenants
• Step 2: Establish trust
• Step 5: Prepare identity mapping
• Step 6: Start migration
• Step 7: Post-migration steps
• Set-SPOCrossTenantRelationship (SharePoint Online PowerShell)
• Get-SPOCrossTenantCompatibilityStatus (compatibility check)
• Purview: sensitivity labels for SharePoint/OneDrive files
• Purview: retention (policies and labels)
• Microsoft 365 Backup: overview

Related MSAdvance services: Services · Modern Workplace · Microsoft 365 security & compliance.

21. Conclusion: how to execute a cross-tenant OneDrive migration without losing control

A Microsoft 365 cross-tenant OneDrive migration succeeds when it is built on four pillars: a real assessment (blockers and limits), identity and mapping (permissions and links), wave-based execution (operations and support), and post-migration governance (Purview, access recertification, and external sharing control).

Typical next steps:

• Select a representative pilot (profiles, volume, external sharing).
• Define and validate identity mapping with key users and groups.
• Plan waves with windows, support capacity, and practical communications.
• Close with access recertification and compliance policies in the target.