OneNote for Windows 10 migration guidance
Important
OneNote for Windows 10 will reach end of support in October 2025. Enterprise customers should switch from OneNote for Windows 10 to OneNote on Windows, which is available from the Microsoft Store and with a Microsoft 365 subscription. OneNote on Windows offers new features and updates and allows you to customize user settings through Group Policy.
This article provides guidance for migrating your organization from OneNote for Windows 10 to OneNote for Windows. It includes instructions for identifying users, customizing migration scripts, and ensuring data integrity throughout the process. You find troubleshooting steps and best practices to help minimize disruption and safeguard user data during the migration.
Identifying users on OneNote for Windows 10:
To identify users or devices in your organization using OneNote for Windows 10 via Microsoft Intune, follow these steps to run a report:
- In Intune, navigate to: All Services > Apps | Monitor > Monitor > Discovered apps, then search for "Office.OneNote."
- Look for the application version starting with
16001.xxxxx.xxxxx.x, to identify OneNote for Windows 10 users. The latest version is16001.14326.22094.0Note
The sample migration script works only with OneNote for Windows 10 devices on version
16001.14326.22094.0
Sample script customization
To ensure a smooth migration to OneNote for Windows, organizations must customize the following sample script to complete these functions:
Installs OneNote on Windows on user devices. For more information, see Deployment guide for OneNote
Updates OneNote for Windows 10 to the latest build to incorporate important features and prevent data loss during the migration of unsynced notes.
Note
This script does not update OneNote for Windows 10 devices that aren't on version 16001.14326.22094. IT admins must upgrade these devices according to their organization's policy.
Terminates all OneNote for Windows 10 processes.
Backs up any unsynced notebooks to the user's backup folder using the
onenote-uwp://backup:command.- The backups are stored in
C:\temp\OneNoteMigration, however, feel free to edit the path to fit your organization’s needs. - Each backup creates a corresponding folder for each notebook with unsynced sections within this path.
- The backups are stored in
Parse through the
UWPBackUpStatus.jsonto validate the backup was successful.- Uninstalling with a failed backup can lead to data loss.
Note
To perform the backup, OneNote for Windows must be installed, and OneNote for Windows 10 must be updated to version 16001.14326.22094 or later.
- Uninstalling with a failed backup can lead to data loss.
Uninstalls OneNote for Windows 10.
- Ensure OneNote for Windows 10 is uninstalled on a user basis and not on a device basis. This process helps mitigate scenarios where shared devices have unsynced notes removed for all accounts.
Important
Before using the sample script, you must customize it to fit your organization's specific deployment and migration requirements.
#############################################
###### OneNote for Windows 10 ############
###### External Migration Script v5 ######
#############################################
## Creates backupFolder and writes log from script to UWPMigrationResult.log File and Console ##
function writeLogsToFileAndConsole {
Param ([string]$logstring)
$timestamp = Get-Date -Format "yyyy-MM-dd HH:mm:ss"
$logstringWithTimestamp = "[$timestamp] $logstring"
$backupFolder = [System.Environment]::GetFolderPath('LocalApplicationData') + "\Microsoft\OneNote\16.0\Backup"
$outputFile = $backupFolder + "\UWPMigrationResult.log"
if (-not (Test-Path $backupFolder)) {
New-Item -Path $backupFolder -ItemType Directory
}
if (-not (Test-Path $outputFile)) {
New-Item -Path $outputFile -ItemType File
}
Add-content $outputFile -value "$logstringWithTimestamp"
Write-Host "$logstringWithTimestamp"
}
## Checks if OneNote UWP is installed and if app data exists, writes version to log file and console ##
function checkOneNoteUWPInstall {
$folderPath = "$env:LOCALAPPDATA\Packages\Microsoft.Office.OneNote_8wekyb3d8bbwe\LocalState\AppData\Local\OneNote"
$uwpApp = Get-AppxPackage | Where-Object {$_.Name -eq "Microsoft.Office.OneNote"}
if ($null -ne $uwpApp) {
$uwpVersion = $uwpApp.Version
$uwpVersionObject = [System.Version]$uwpVersion
writeLogsToFileAndConsole "UWP OneNote app version: $uwpVersion"
} else {
writeLogsToFileAndConsole "OneNote UWP App is not installed"
exit
}
if (Test-Path $folderPath) {
Write-Host "AppData folder detected"
} else {
($null -ne $uwpApp)
$uwpApp | Remove-AppxPackage
writeLogsToFileAndConsole "AppData folder does not exist and OneNote UWP will now be uninstalled"
exit
}
}
## Checks if OneNote Win32 is installed by checking the existence of the executable file and checks the version ##
function checkOneNoteWin32Install {
$oneNotePath = Join-Path $env:ProgramFiles "Microsoft Office\root\Office16\ONENOTE.EXE"
$registryPath = "HKLM:\SOFTWARE\Microsoft\Office\ClickToRun\Configuration"
$versionValueName = "ClientVersionToReport"
$registry = Get-ItemProperty -Path $registryPath
if (Test-Path $oneNotePath) {
if ($registry.PSObject.Properties[$versionValueName]) {
$versionValue = $registry.$versionValueName
writeLogsToFileAndConsole "OneNote Win32 Version Value: $versionValue is installed at path $oneNotePath"
} else {
writeLogsToFileAndConsole "OneNote Win32 is not installed"
exit
}
}
## Checks for backup folder path
$registryPath = "HKCU:\SOFTWARE\Microsoft\Office\16.0\OneNote\Options\Paths"
$backupValueName = "BackupFolderPath"
if (Test-Path $registryPath) {
$registry = Get-ItemProperty -Path $registryPath
if ($registry.PSObject.Properties[$backupValueName]) {
$backupValue = $registry.$backupValueName
writeLogsToFileAndConsole "OneNote Win32 Backup Path Value: $backupValue"
}
}
}
## Updates OneNote for Windows 10 to the latest version available ##
function updateUWPVersion {
$uwpApp = Get-AppxPackage | Where-Object {$_.Name -eq "Microsoft.Office.OneNote"}
if ($null -ne $uwpApp) {
$uwpVersion = $uwpApp.Version
$uwpVersionObject = [System.Version]$uwpVersion
$updatedVersion = "16001.14326.22008.0"
$updatedVersionObject = [System.Version]$updatedVersion
$unsupportedVersion = "16001.14327.10000.0"
$unsupportedVersionObject = [System.Version]$unsupportedVersion
if ($uwpVersionObject -ge $unsupportedVersionObject)
{
writeLogsToFileAndConsole "Unsupported version of OneNote UWP app. Please check the Microsoft Store for updates"
exit
}
if ($uwpVersionObject -lt $updatedVersionObject)
{
writeLogsToFileAndConsole "You must upgrade OneNote UWP to a version higher than 16.0.14326.21802. Please check the Microsoft Store"
exit
}
else
{
writeLogsToFileAndConsole "OneNote UWP will backup and uninstall"
}
}
else
{
writeLogsToFileAndConsole "No OneNote UWP detected therefore no need for migration"
exit
}
}
## Terminates the OneNote for Windows 10 app before executing the rest of the migration script ##
function killProcess {
if (Get-Process -Name "OneNoteIm" -ErrorAction SilentlyContinue)
{
try
{
$uwpProcess = Get-Process -Name "OneNoteIm"
Stop-Process -Id $uwpProcess.Id -Force
Start-Sleep -Seconds 10
}
catch
{
writeLogsToFileAndConsole "An error occurred when killing the current OneNote UWP process: $($_.Exception.GetType().FullName)"
writeLogsToFileAndConsole "$($_.Exception.Message)"
exit
}
writeLogsToFileAndConsole "OneNote UWP process killed"
}
}
function launchBackUp {
try
{
Start-Process "onenote-uwp://backup:"
Start-Sleep -Seconds 60
writeLogsToFileAndConsole "OneNote UWP backup initiated"
}
catch
{
writeLogsToFileAndConsole "An error occurred when starting the backup: $($_.Exception.GetType().FullName)"
writeLogsToFileAndConsole "$($_.Exception.Message)"
exit
}
writeLogsToFileAndConsole "OneNote UWP backup in progress"
}
## Parses the results in the json files to validate that the backup was successful ##
function parseJson {
try
{
$localAppDataPath = [System.Environment]::GetFolderPath('LocalApplicationData')
$jsonPath = "$localAppDataPath\Packages\Microsoft.Office.OneNote_8wekyb3d8bbwe\LocalState\AppData\Local\OneNote\16.0\UWPBackUpStatus.json"
if(!(test-path $jsonPath)){
writeLogsToFileAndConsole "Backup Json file path is not valid"
exit
}
$backupJsonFileContent = Get-Content -Path $jsonPath -Raw | ConvertFrom-Json
$status = $backupJsonFileContent."UWP Backup Status"
if ($status -eq "Completed") {
$jsonPath2 = "$localAppDataPath\Packages\Microsoft.Office.OneNote_8wekyb3d8bbwe\LocalState\AppData\Local\OneNote\16.0\UWPSyncStatus.json"
if(test-path $jsonPath2)
{
$syncStatusJsonContent = Get-Content -Raw -Path $jsonPath2
$syncStatusJsonObject = COnvertFrom-Json $syncStatusJsonContent
foreach ($key in $syncStatusJsonObject.PSObject.Properties)
{
$value = $syncStatusJsonObject.$($key.Name)
if ($value.StartsWith("Contains pending outbounding changes: true,"))
{
if ($backupJsonFileContent."Number of sections Backed up" -eq 0)
{
writeLogsToFileAndConsole "No error occurred when backing up but outbounding changes were not backed up successfully"
exit
}
else
{
break
}
}
}
}
writeLogsToFileAndConsole "OneNote UWP backup is completed and status is saved"
}
elseif ($status -eq "")
{
writeLogsToFileAndConsole "$status"
writeLogsToFileAndConsole "No error occurred but backup did not finish. We cannot continue migration. Consider increasing the Start-Sleep time in line 130 and rerun the script"
exit
}
else
{
writeLogsToFileAndConsole "No error occurred but backup status is $status. We cannot continue migration. Consider increasing the Start-Sleep time in line 130 and rerun the script"
exit
}
}
catch
{
writeLogsToFileAndConsole "An error occurred when finishing the backup: $($_.Exception.GetType().FullName)"
writeLogsToFileAndConsole "$($_.Exception.Message)"
exit
}
}
## Copies the backup files to the local app data folder ##
function moveBackup {
try
{
$localAppDataPath = [System.Environment]::GetFolderPath('LocalApplicationData')
$sourcePath = "$localAppDataPath\Packages\Microsoft.Office.OneNote_8wekyb3d8bbwe\LocalState\AppData\Local\OneNote\16.0\BackUp\"
$destinationPath = [System.Environment]::GetFolderPath('LocalApplicationData') + "\Microsoft\OneNote\16.0\Backup\"
Copy-Item -Path $sourcePath\* -Destination $destinationPath -Recurse -Force
$sourcePath = "$localAppDataPath\Packages\Microsoft.Office.OneNote_8wekyb3d8bbwe\LocalState\AppData\Local\OneNote\16.0"
$fileExtensions = "*.json", "*.txt"
foreach ($fileExtension in $fileExtensions)
{
$files = Get-ChildItem -Path $sourcePath -Filter $fileExtension
foreach ($file in $files) {
Copy-Item -Path $file.FullName -Destination $destinationPath -Force
}
}
}
catch
{
writeLogsToFileAndConsole "An error occurred when moving the backup files: $($_.Exception.GetType().FullName)"
writeLogsToFileAndConsole "$($_.Exception.Message)"
exit
}
writeLogsToFileAndConsole "Backup files copied successfully from $sourcePath to $destinationPath"
}
function uninstallUWP {
$uwpApp = Get-AppxPackage | Where-Object {$_.Name -eq "Microsoft.Office.OneNote"}
if ($null -ne $uwpApp) {
$uwpApp | Remove-AppxPackage
writeLogsToFileAndConsole "OneNote UWP version uninstalled"
}
}
function MainRoutine {
checkOneNoteWin32Install
checkOneNoteUWPInstall
updateUWPVersion
launchBackUp
killProcess
parseJson
moveBackup
uninstallUWP
}
## Executes the main routine ##
MainRoutine
Accessing migrated notes
After migration, users can retrieve their notes by:
- Opening the new OneNote on Windows application.
- Signing into their account.
- Opening their notebooks.
If any notes are missing, check the backup folder that was created in the previous steps.
To review backups through OneNote on Windows:
- Navigate to File -> Open Backups -> Navigate to the backup file path.
Troubleshooting
Review the
UWPBackupStatus.jsonandUWPSyncStatus.jsonfiles in the user’s backup folder for detailed information on the backup and sync statuses.For errors encountered during migration, refer to the log file located in the backup generated previously (step 1.d).
If the onenote-uwp://backup: command fails:
- Ensure that the OneNote for Windows 10 app is the default app linked to the
onenote-uwpprotocol. - Consult the relevant support article to ensure correct protocol attachment to OneNote for Windows 10.
Caution
Be cautious when using commands found online. Always test commands in a controlled environment before deploying them organization-wide to avoid unintended consequences, such as those resulting from the Remove-AppxPackage command.
For more assistance or inquiries, contact Microsoft Support.