How to migrate an on-premise SharePoint document library to SharePoint online with Powershell


There are a couple of ways in order to migrate a document library from your on premise SharePoint farm to the SharePoint online. You can use third party tools to migrate to SharePoint online, you can manually move files between SharePoint libraries or you can use Windows Powershell cmdlets to migrate a document library to SharePoint online. In this blog post, I want to discuss the Windows Powershell cmdlets to migrate a document library to SharePoint online.

Unfortunately Microsoft documentation on this topic is so vague and it takes a couple of hours from me to get a heck of that. So here is the complete explanation on how to migrate a document library from on premise SharePoint farm to SharePoint online with Windows Powershell cmdlets.


  1. Install SharePoint online management shell
  2. Setup directories
  3. Create azure storage account and get the key
  4. Create a new package from an on premise SharePoint document library
  5. Convert the package to SPOMigration Targeted Package
  6. Upload the package to the storage account
  7. Submit package data to site collection to create new migration job


Step 1 – Install SharePoint online management shell

You can install SharePoint online management shell from this link:

If you previously have installed prior versions of SharePoint online management shell, first you have to remove them and then install the latest version from the link above. After the installation of the SharePoint online management shell, open it and run it as an administrator.

Step 2 – setup directories

This is the part that normally people get confused. You need the following directories on your local machine:

  1. $sourcePackage : a shared directory which contains content files
  2. $sourcePackagePath: a local directory which contains XML files
  3. $targetPackage: a local directory which contains ready to upload package

For example, here are my values for these parameters:

Server04 is the name of the server which I have shared the folder, and because I want to do a full export without any compression, I specified the directories for content files and xml files as export.cmp

Step 3 – Create azure storage account and get the key

You can use this guide to create an azure storage account and get the key:

step 4 – create a new package

In this step, we will produce the content and xml meta data out of the SharePoint document library.

We use Export-SPWeb to export the contents of the document library along with XML meta data. Here is the description of the parameters:

  • $sourceWeb : the on premise SharePoint site URL
  • $sourcePackagePath : where you want to store the files
  • $sourceDocLib : the relative path to the document library that you want to export , like ‘/mydocs/’
  • You have to use NoFileCompression switch

When you run the above command to export a document library from on premise SharePoint, it will create a directory in $sourcePackagePath with both data and xml files. You have to browse to that location and copy all the content files (*.dat) to $sourcePackage folder and xml files to $sourcePackagePath.

After doing this, your directories will look like this:

Step 5 – convert the package

Now you have to convert the package to make it ready to be uploaded to the azure storage account:

Before running this command, make sure you have the proper value for the $creds variable:

You have to enter the Office 365 global admin account here.

Step 6 – upload the package to the azure

In this step, we upload package into the azure storage account, finally snapshotting all files

Step 7 – submit the package to create a new migration job

We submit package data to site collection to create new migration job

In order to make sure that the job placed correctly in the queue, you can use the Microsoft Azure storage explorer ( tool to browse the queue.

after a minute, you can check the SharePoint online document library to see the files are migrated correctly:

Of interest:

  • If you package a document library and migrate it to SharePoint online by this method, then you want to package the same library and copy to a different document library in the same SharePoint online site, only the changed files will be moved
  • If you have the same columns added to your on premise SharePoint document library and SharePoint online, after the migration the columns will be filled out with their respective values.

  • You can check the status of the timer job in the logs which can be accessed by the Azure storage explorer.

Here is the complete Powershell script for the entire process of migrating from on premise SharePoint document library to SharePoint online:



MCSE, PMP, With more than 12 years experience in Microsoft technologies.

View all posts by

13 thoughts on “How to migrate an on-premise SharePoint document library to SharePoint online with Powershell

  1. This may be a simple question but I can’t seem to find any article which mentions it. Must the target library path be created before hand on SharePoint online for each library being migrated? Whenever I run the convert package it says the target path does not exist – I was hoping it would be created by the powershell command if it did not exist. The only one that worked was “Shared Documents” because that was there by default.Thanks

    1. yes, you have to create the document library in the target sharepoint site beforehand.
      Moreover, if you want to migrate the meta data of the documents in library(custom columns), you have to also create them in the target document library as well before migration.

  2. It may be a dumb question, but I can’t find the answer anywhere. By running this, are all source documents and files removed? I ask because I intend to do a few test run’s of this before doing the final migration. Thanks for the help.

  3. Hi Farshid, thanks for the sharing. I have two comments that I would like to share:

    – Are there any kind of boundaries that should be considered (i.e. number of docs, size of the package)?
    – Regarding the needs to create structures prior the migration. The reason is that schemas produced by the Export-web cmdlet are ignored by the ConvertTo-SPOMigrationTargetedPackage one?


    1. Good Questions Leo!
      I did not see any limitations or boundaries in terms of number of items, size, … It should do the job and the boundaries are those which inherited from SharePoint. But I will run a POC on a doc library with millions of items and let you know the result.
      for your second question, unfortunately the official documentation on ConvertTo-SPOMigrationTargetedPackage does not explain anything good. I have tried many ways and this is the only way which is working. I think the problem is the output of Export-Web is not understandable by ConvertTo-SPOMigrationTargetedPackage , so we have to specify explicitly the schema.

  4. I keep getting an error “ConvertTo-SPOMigrationTargetedPackage : Target list or document library was not found on the target web” I have added the library to SPO, but it continues to throw that exception. I am migrating from SharePoint Foundation 2010. What may I be doing wrong?

  5. Hi, Thanks for your article. Likewise please advise me how to migrate online sharepoint document library to on premise sharepoint? Please explain me with more details

Leave a Reply