SharePoint Migration Tool (SPMT): guida pratica

Il SharePoint Migration Tool (SPMT) è lo strumento gratuito di Microsoft per copiare in Microsoft 365 i contenuti che oggi stanno su un file server, su una cartella di rete o su SharePoint Server 2010, 2013, 2016 e 2019. Lo installi su un PC Windows, gli dici da dove prendere i dati e dove metterli (SharePoint Online, OneDrive o Teams) e lui si occupa di scansione, caricamento e importazione. Va bene per file server e per siti SharePoint senza personalizzazioni. Quando i volumi crescono o i siti sono pieni di codice custom servono altri strumenti, e in fondo vediamo quali.

Qui trovi quello che controlliamo ogni volta che usiamo SPMT in un progetto di migrazione a SharePoint Online. Ogni dato rimanda alla documentazione Microsoft, verificata a ottobre 2026.

Cosa migra SPMT e verso dove

Secondo la pagina di presentazione su Microsoft Learn, le sorgenti supportate sono:

• Condivisioni di rete e cartelle locali (il classico file server aziendale).
• SharePoint Server 2010, 2013, 2016 e 2019 e SharePoint Foundation 2010 e 2013.
• Workflow: quelli predefiniti di SharePoint Server 2010 e quelli creati con SharePoint Designer 2010 e 2013, che vengono convertiti in flussi Power Automate.

Le destinazioni sono SharePoint Online, OneDrive e Teams. Da SharePoint Server SPMT porta file, cartelle, elementi di elenco, permessi, versioni, tipi di contenuto, term store, navigazione e web part, come riportato nella tabella delle funzioni supportate. La migrazione di interi siti però vale solo per siti «out of the box», senza codice o componenti di terze parti.

Spesso a far partire il progetto è la scadenza del supporto: ne parliamo in SharePoint Server 2016 e 2019 fuori supporto.

Requisiti: cosa verificare prima di installarlo

Computer e sistema operativo

Microsoft pubblica due configurazioni nella pagina dei prerequisiti di SPMT. Quella consigliata:

• Processore 64 bit quad core o superiore.
• 16 GB di RAM.
• Disco SSD con 150 GB liberi.
• Scheda di rete da 1 Gbps.
• Windows Server 2016 o Windows 10 (o successivi) con .NET Framework 4.6.2 o successivo.

Il minimo (dual core, 8 GB di RAM, 150 GB su disco tradizionale) funziona, ma Microsoft avverte che sarà lento. I 150 GB servono alla cartella di lavoro dove SPMT prepara i pacchetti prima di caricarli: per impostazione predefinita sta in %appdata%\Microsoft\MigrationTool, come indicato nelle impostazioni di SPMT.

Account e permessi

Lato Microsoft 365 ti serve un account SharePoint Administrator o Global Administrator per migrare a livello di organizzazione, oppure l'account di amministratore della raccolta siti se lavori su un solo sito. Lo dice la guida all'installazione. Sulla sorgente basta la lettura.

Un dettaglio che fa perdere tempo: se SharePoint Server ha più provider di autenticazione, tra cui quella Windows, quest'ultima non è supportata da SPMT.

Rete ed endpoint

La macchina con SPMT deve raggiungere una ventina di indirizzi Microsoft, tra cui login.microsoftonline.com, graph.microsoft.com, *.sharepoint.com, *.blob.core.windows.net e *.queue.core.windows.net. L'elenco completo è nella stessa pagina dei prerequisiti: passalo a chi gestisce il firewall prima di iniziare. Attenzione al proxy: la guida alla creazione delle attività dice che le connessioni via proxy non sono supportate e generano errori come «SharePoint login fail». Se il proxy è obbligatorio, le impostazioni spiegano come abilitarlo da file di configurazione.

Installazione

Scarichi SPMT dal link della versione generale (aka.ms/spmt-ga-page) riportato nella pagina di installazione. Al primo avvio ti chiede le credenziali Microsoft 365 della destinazione. Mentre lavora, SPMT salva lo stato della sessione in un elenco nascosto nel tuo OneDrive: per questo puoi riprendere una migrazione anche da un altro computer, accedendo con lo stesso account. Tutte le funzioni sono disponibili anche da PowerShell.

Una migrazione con SPMT, passo per passo

1. Scansione

Da SPMT 4.0 la valutazione dei siti SharePoint Server è integrata: lanci una scansione, guardi la dashboard con inventario e rischi e scarichi il report completo. Per i file server puoi attivare l'impostazione Only perform scanning e fare solo la pre-analisi. Noi la facciamo sempre: percorsi troppo lunghi e nomi non validi escono qui, non a metà migrazione.

2. Sorgente e destinazione

Scegli Add new migration e poi il metodo: URL singolo (un sito, un elenco o una raccolta) oppure file CSV/JSON per più attività insieme. Per i siti scegli tra struttura classica e moderna, ed eventualmente l'associazione a un hub. Tutti i passaggi sono nella guida alla creazione delle attività.

3. Impostazioni da decidere prima

Le impostazioni che contano di più:

• Versioni: se le disattivi passa solo l'ultima versione di ogni file; se le attivi puoi tenerle tutte o limitarne il numero.
• Permessi: interruttori separati per i permessi del file server e per quelli di SharePoint.
• Filtri: file creati o modificati dopo una certa data, estensioni da escludere, file nascosti.
• Caratteri non validi: SPMT può sostituire virgolette, asterisco, due punti, simboli di minore e maggiore, punto interrogativo, barre e barra verticale con un carattere a tua scelta. Se l'opzione è spenta, quei file vengono saltati.
• Nuovi tentativi: puoi far ripetere automaticamente l'attività fino a 5 volte.

Sui permessi del file server sappi che passano solo Lettura, Scrittura e Controllo completo: Scrittura diventa «Collaborazione» su SharePoint, mentre i permessi speciali come Nega non vengono salvati. Se avevi cartelle protette con un Nega, vanno riviste prima.

4. Migrazione e report

Con Start SPMT esegue in parallelo scansione, creazione dei pacchetti, caricamento cifrato su un contenitore Azure dedicato e importazione, come spiega la pagina su come funziona SPMT. A fine attività hai i report nella cartella di lavoro: il file da aprire per primo è il riepilogo degli errori.

5. Passaggi incrementali

Un'attività completata si può salvare e rilanciare per copiare solo i file nuovi o modificati. Le regole sono nella guida alle attività: se il file sorgente è più recente viene copiato, altrimenti no. Per i file server il confronto avviene sul percorso, per SharePoint Server sul GUID dell'elemento. Due avvertenze: l'impostazione è globale e va decisa prima di inviare il primo job, e Microsoft sconsiglia di rinominare o spostare i file migrati prima dell'ultimo passaggio, perché verrebbero sovrascritti. Nel registro di controllo vedrai cancellazioni fatte dall'account di sistema: secondo le FAQ è normale, perché SPMT elimina la copia in destinazione quando la sorgente è più recente. E ricorda che SPMT copia, non sposta: gli originali restano al loro posto.

Mappatura utenti

Per conservare i permessi ogni utente on-premises deve avere un corrispondente in Microsoft 365. Il modo più semplice è sincronizzare Active Directory con Microsoft Entra ID: in quel caso la mappatura automatica, attiva di default, fa quasi tutto da sola. Se le identità non coincidono prepari un file di mappatura utenti: un CSV senza riga di intestazione con tre colonne.

• Colonna A: nome di accesso dell'utente nella sorgente (da SharePoint Server 2013 in poi puoi usare anche il SID).
• Colonna B: UPN dell'utente in Microsoft 365.
• Colonna C: TRUE se la destinazione è un gruppo di Active Directory, FALSE altrimenti.

Con un file personalizzato Microsoft indica di disattivare la mappatura automatica. Senza alcuna mappatura i file prendono i permessi predefiniti della destinazione. SPMT migra solo i gruppi SharePoint predefiniti e non permette di mappare un gruppo AD su un gruppo SharePoint.

Migrazioni massive con file CSV o JSON

Con decine di cartelle conviene un file con una riga per ogni coppia sorgente/destinazione. Il formato CSV prevede sorgente, raccolta e sottocartella di origine, poi sito, raccolta e sottocartella di destinazione, più due colonne opzionali per gli hub. Per un file server le colonne 2 e 3 restano vuote. In JSON i campi minimi sono SourcePath e TargetPath. Due cose che ci hanno fatto perdere tempo:

• La raccolta «Documenti condivisi» va indicata con il nome interno Documents, altrimenti ottieni «invalid document library». Su siti non in inglese verifica il nome interno da _layouts/15/viewlsts.aspx.
• Le righe duplicate bloccano tutto con «A duplicate task has already been created».

SPMT controlla il file riga per riga e non ti fa partire finché non correggi gli errori segnalati. Per volumi importanti le FAQ suggeriscono di installare SPMT su più computer o macchine virtuali e lanciare job massivi in parallelo.

Limiti e cosa SPMT non migra

• Percorso: l'intero percorso, nome del file compreso, deve stare sotto i 400 caratteri.
• Dimensione file: dalla versione 3.4.122.0 il limite è 250 GB per file.
• Nomi e tipi di file non validi: valgono le regole di OneDrive e SharePoint.
• Tenant to tenant: SPMT non migra da un tenant Microsoft 365 a un altro; per questo Microsoft rimanda alle soluzioni cross-tenant.
• Da SharePoint Server non passano: struttura senza contenuti, pagine master, moduli InfoPath, moduli Nuovo/Modifica/Visualizza personalizzati. Il modello del sito di destinazione lo decide SPMT. L'elenco è nelle FAQ.
• Permessi ereditati da SharePoint on-premises: passano solo quelli univoci.
• Pagine personalizzate e web part di terze parti non sono supportate.

Prima di migrare, decidi cosa va su OneDrive o SharePoint: file personali e file di reparto non vanno nello stesso posto.

Errori più frequenti e come risolverli

La pagina di risoluzione dei problemi comuni elenca decine di codici. Quelli che incontriamo più spesso:

• Target path is too long: percorso oltre i 400 caratteri. Accorcia nomi di cartelle o punta la destinazione più in alto nella struttura.
• Not enough disk space to pack the file o 0x02040012: la cartella di lavoro è piena. Liberala o spostala su un disco più grande.
• 0x0204000A, 0x02050001, 0x0204000D: qualche file nella cartella di lavoro di SPMT era aperto. Chiudi file e cartelle aperti lì dentro e riavvia la migrazione.
• 0x0201000C, 0x02010018, 0x02030001: credenziali o rete. Controlla l'account, prova ad aprire il sito dal browser della stessa macchina.
• 0x0131000F: il file è in check-out sulla sorgente. Fai fare il check-in e rilancia.
• 0x02010020: stai migrando le versioni ma la raccolta di destinazione non ha il controllo versioni attivo.
• 0x02030003: troppi elementi con permessi univoci. Semplifica la struttura dei permessi prima di riprovare.

Quando conviene Migration Manager invece di SPMT

Migration Manager vive nell'interfaccia di amministrazione di SharePoint: installi un agente su uno o più server e le attività vanno in automatico al primo agente libero. Per le condivisioni di rete il server sorgente deve supportare SMB 2.0 o superiore. Ha senso quando:

• devi migrare file server grandi e vuoi distribuire il lavoro su più macchine con un unico pannello di controllo. Le FAQ di SPMT lo indicano proprio per orchestrare i job in automatico;
• la sorgente è Google Workspace, Box, Dropbox o Egnyte, che SPMT non gestisce;

Per SharePoint Server, invece, lo strumento indicato da Microsoft nella panoramica delle migrazioni resta SPMT. La stessa pagina precisa che Migration Manager non supporta Amazon S3 né Azure Blob Storage.

Quando serve uno strumento a pagamento

SPMT copre bene file server e siti standard. Valuta uno strumento commerciale, come quelli di Quest, ShareGate o altri vendor, se ti trovi in uno di questi casi:

• siti SharePoint Server con soluzioni custom, pagine personalizzate, pagine master o web part di terze parti;
• moduli InfoPath o moduli di elenco personalizzati da portare insieme ai dati;
• vuoi creare prima la struttura dei siti e caricare i contenuti dopo.

Come lavoriamo noi

Lo strumento è la parte facile. Una migrazione riesce per il lavoro fatto prima: inventario, pulizia dei duplicati, struttura delle raccolte, permessi per gruppi e non per persone. Noi partiamo da una scansione di prova, concordiamo la nuova struttura, migriamo a ondate e chiudiamo con un passaggio incrementale prima del cambio definitivo. Per il dopo, con metadati e regole di conservazione, c'è la nostra gestione documentale su SharePoint.