How to use the SharePoint Migration Tool

The SharePoint Migration Tool is a tool that migrates your files from SharePoint on-premises document libraries or regular file shares and easily moves them to your SharePoint Online tenant. It is available to all Office 365 users.

Notes: 

Before you begin

When you first launch the SharePoint Migration Tool, you will be prompted for your Office 365 username and password. The Office 365 credentials you provide will be where the files will be migrated.

Recommendation

CPU

64-bit Quad core processor or better

RAM

16 GB

Local Storage

Solid state disk: 150 GB free space

Network card

1 Gbps

Operating system

Windows Server 2012 R2 or Windows 10 client

.NET Framework 4.6.2

Minimum requirement

CPU

64-bit 1.4 GHz 2-core processor or better

RAM

8 GB

Local Storage

Hard disk: 150 GB free space

Network card

High-speed Internet connection

Operating system

Windows Server 2008 R2, Windows 7 updated or better

.NET Framework 4.6.2

What happens to the permissions on a file when it is migrated?

The location of your on-premises data, and whether you have synchronized your Active Directory accounts to Azure Active Directory (AAD), can affect the permission settings on your files after they have been migrated to SharePoint Online.

Note: Certain settings can affect how permissions on your files will be handled. See the Advanced Settings section below, specifically the Azure Active Directory lookup, Preserve permissions, and User Mapping file settings.

Syncing your environment: In order to maintain existing on-premises file permissions, there must be a corresponding user in SPO. The easiest way to accomplish this is to synchronize your Active Directory accounts to Azure Active Directory (AAD).

Note: You can upload a custom user mapping file to the SharePoint Migration Tool.

File share

SharePoint on-prem files

User mapped between on-premises and SPO (either Dirsync has been run or a user mapping file provided)

There are only two types of permissions that will be migrated: Read and Write.

If a file has Write permission for user1, then the file will be set to Contribute for user1 in SPO. If a file has Read permission for user1, then the file will be set to Read for user1 in SPO.
Note: At this time, the special permissions, such as Deny, will not be saved.

All the unique permissions on a file will be migrated to SPO.  Inherited permissions will not be migrated.

No user mapping (not synced, no user mapping file)

Files will be assigned the default permission of the location to which it has been migrated in SPO.

Files will be assigned the default permission of the location to which it has been migrated in SPO.

Where is your data currently located?

Before you start using the SharePoint Migration Tool, note where your data is located and where you want those files. You will be prompted for the current location of your data files and the location of the SharePoint Online site collection where you want them moved. The SharePoint Migration Tool lets you select from two sources from which to migrate your data: from an on-premises SharePoint Server 2013 site or from a local file share or network path.

  • SharePoint on-premises: If you select the SharePoint on-premises option, you will be asked to enter the name of the SharePoint Server site where your files are located and prompted for your credentials for that site. You will indicate what document library you wish to migrate.

    Note: The SharePoint Migration Tool supports SharePoint Server 2013.

  • File share: If you select the file share option, you will be asked to enter the location of the file share, the URL of the SharePoint Online site, and the document library where they will be moved.

Using the SharePoint Migration tool

If you don't have it yet, download the SharePoint Migration Tool.

Migrating data files from SharePoint Server document libraries

  1. Start the SharePoint Migration Tool, and then click Next.

  2. Enter your Office 365 username and password, and then click Sign in.

  3. Select Choose a source and destination.

  4. Select SharePoint Server (on-premises).

  5. Enter the SharePoint Server 2013 site URL where your data is currently located. Click Next.

  6. Enter your username and password to the SharePoint Server site; username must use the format of someone@example.com. Click Sign in.

    Note: If you have already signed in to that site once while using this tool, you won't be prompted again for the same site.

  7. Choose the document library where your files are located. The drop-down list will contain all your possible choices.

  8. Enter the URL of the SharePoint Online site where you want your files migrated.

  9. Select the document library to where your files will be moved.

  10. Click Add. This task will be added to the list. If you want to select another set of data files to migrate, click Choose a source and destination.

Migrating data files from a local file share

  1. Start the SharePoint Migration Tool, and then click Next.

  2. Enter your Office 365 username and password, and then click Sign in.

  3. Select Choose a source and destination.

  4. Select File share.

  5. Enter the path of the file share where your data is located. Click Next.

  6. Enter the URL of the SharePoint Online site where you want your files migrated, and then enter your username and password to the SharePoint Server site. Click Sign in.

    Note: If you have already signed in to that site once while using this tool, you won't be prompted again for the same site.

  7. Choose the document library to where your files will be moved.

  8. Click Add. This task will be added to the list. If you want to select another set of data files to migrate, click Choose a source and destination.

  9. When you have finished selecting your sources, click Migrate.

Bulk migration using a CSV file

If you have many sources to migrate, you can use a CSV file to do a bulk migration. Create a comma-delimited file CSV file that includes the following the following 6 columns. Each field is separated by a comma. If the value within a column contains a comma, surround it double quotations.

For more information on how to create a CSV file for data content migration, see How to format your CSV file for data content migration.

To use a CSV file for bulk migration

  1. Open the SharePoint Migration Tool, and then click Next.

  2. Enter your Office 365 username and password, and then click Sign in.

  3. Select Choose a source and destination.

  4. Select Use a CSV file for bulk migration. Enter the location of your CSV file, or click Choose File to locate it. Click Add.

    Note: If you are migrating files from an on-premises SharePoint Server, you will be prompted for your username and password for that site unless you provided those credentials in previous steps.

    Note: Any errors in your CSV file will be detected on a line-by-line basis. The error will indicate which line or lines contains the errors. You will not be able to proceed until you correct the errors in your CSV file.

  5. If your CSV file is successfully added without errors, the job will be added to your list of sources and destinations.

  6. If you want to select another set of data files to migrate, click Choose a source and destination.

  7. When you have finished selecting your sources, click Migrate.

Monitoring and reporting status of migration jobs

After you click Migrate, the progress of your migration jobs will be displayed. As they complete, you can view either detailed or summary reports of an individual job or a single summary report that includes all migration jobs submitted during this session.

To view detailed reports

  1. Click the down arrow directly below the migration job.

  2. Click View Task Report. A folder opens containing three different reports:

    • FilesReport.csv

    • FilesSummary.csv

    • ScanSummary.csv

To view a summary report all submitted jobs

  • Click Open Report.

    A report folder opens containing the summary report.

Resuming migration jobs

If you need to close the migration tool before a submitted job has completed, you can restart the tool from any computer.

Note: To resume a submitted migration job, it has to have been running at least 5 minutes. It will be paused at the point you closed the SharePoint Online Migration Tool. If your submitted job was running less than 5 minutes before the tool closed, you must resubmit the job.

To resume migration jobs

  1. Launch the SharePoint Migration Tool. Click Sign In using the same Office 365 username and password you used when you originally submitted the job.

  2. After you sign in, a screen displays any paused migrations, providing details about what has been completed and what remains.

  3. If you want to add additional migration tasks, click Select new sources and destinations. Otherwise, click Next. Your migration jobs will be resumed. If you are migrating files from an on-premises SharePoint Server, you will be prompted for your username and password for that site.

Incremental migration

After a migration task has completed, it can also be saved to be rerun at a later date, allowing you to move only those new or updated files in the source location. 

To do this, go to Settings and turn Enable incremental migration to On

Note: This must be set before the initial migration job is submitted. This setting is global; it will apply to all the tasks you submit.

  1. Start the SharePoint Migration Tool, and then click Next.

  2. Enter your Office 365 username and password, and then click Sign in.

  3. The screen titled "Where's your data" displays. Click Cancel.

  4. Click the settings gear.

  5. Turn Enable incremental migration to On and close the window.

  6. Enter your tasks as usual, and then migrate.

  7. After a task completes, click Yes when you see the following prompt:

    Incremental migration save prompt_C3_2017919144129

Advanced Settings

Advanced settings should only be changed or managed by your IT professional. The advanced settings are in the following categories:

Setting

Description

Only perform scanning

If you wish to scan the files as a pre-assessment to migration, turn Only perform scanning on.

Enable incremental migration

By setting enable incremental migration to On, it lets you rerun the migration jobs at a later date, migrating only the changes or additions since the previous run.

Important: If you wish to be able to submit this job again for incremental migration, this setting must be set to On before the initial migration job is submitted.

Migrate file version history

If set to No, only the most recent version of the file will be migrated. If set to Yes, you can choose whether to keep all versions, or limit it to a specific number.

Do not migrate hidden files

If set to On, hidden system files will not be migrated.

Do not migrate files created before

If you choose to limit which files are migration based on creation date, set your values in this section. This may be to limit the number of files migrated or to adhere to overall company governance policy regarding file retention.

Do not migrate files modified before

If you choose to limit what files are migration based on modified date, set your values in this section. This may be to limit the number of files migrated or to adhere to overall company governance policy regarding file retention.

Do not migrate files with these extensions

To prevent certain file types from migrating, list each extension, separating it with a vertical bar. For example, mp4|avi|mkv. Do not include the leading "." before the extension name.

Do not migrate files and folders with invalid characters

By default, the setting is set to Off. This is the recommended setting. The tool will attempt to move all the files without filtering on characters. If any file can't be accepted into SPO, a failure message will be generated for that file.

If set to On, the tool will skip any potential special characters. While this can improve performance when the source potentially contains a high number of files containing invalid characters, it also has drawbacks. To prevent malicious activities, source packages that generate more than 100 errors to the destination server will be blocked. As a result, all valid files in that package would also be blocked.

Azure Active Directory lookup

By default, this is set to On. If no User mapping file is provided by the user, then Azure Active Directory is used as the default for user mapping.

Preserve user permissions

By default, this is set to On. If set to Off, no permissions will be preserved.

User mapping file

By default, Azure AD lookup is used to map users when submitting migration jobs. If you wish to use your own mapping file, select the file to be used by clicking Choose file. If you choose to use a custom user mapping file and you want to preserve user permissions, turn off Azure Active Directory lookup. By doing so, if a user isn't found in the mapping file, the tool won't look it up in AAD.

SharePoint Migration Tool work folder

By default, a temp folder will be created. If you wish to specify a specific working folder, enter the name here.

Use custom Azure storage

If you wish to use your own Azure storage, set this value to On.

If you choose to turn on, additional fields will display to enter your account and key, and settings to select if you want to enable or disable encryption, and whether temporary files are deleted when migration is complete.

Related Topics

Introducing the SharePoint Migration Tool
How the SharePoint Migration Tool works
How to format your CSV file for data content migration
Create a user mapping file for data content migration
SharePoint Online and OneDrive Migration Speed
SharePoint Migration Tool Feedback and Support Forum

Connect with an expert
Contact us
Expand your skills
Explore training

Was this information helpful?

Thank you for your feedback!

Thank you for your feedback! It sounds like it might be helpful to connect you to one of our Office support agents.

×