/commands/purview/get-label-sensitivity-labels
Get-Label: list sensitivity labels and label policies in Security & Compliance PowerShell
- tool
- Microsoft Purview (Security & Compliance PowerShell)
- versions
- Security & Compliance PowerShell, ExchangeOnlineManagement 3.x
- os
- windows, linux, macos
Sensitivity labels are read with Get-Label in Security & Compliance PowerShell (not in Exchange Online PowerShell). Connect with Connect-IPPSSession, then:
Get-Label | Format-Table Priority,DisplayName,Name,Guid -AutoSizeDisplayName is what users see in Office apps; Name and Guid identify the label in cmdlets and in Microsoft Graph or Information Protection APIs. Priority is the order in the label list (a higher value is a more sensitive label).
One label in detail
Get-Label -Identity "Confidential" | Format-List
Get-Label -Identity "Confidential" -IncludeDetailedLabelActions | Format-List DisplayName,ContentType,*Action*-IncludeDetailedLabelActions expands the label's actions (encryption, marking, protection settings) into readable properties. Sub-labels show their parent in ParentId.
Who gets the labels
Labels reach users through label policies:
Get-LabelPolicy | Format-Table Name,Labels,ExchangeLocation
Get-LabelPolicy -Identity "Global label policy" | Format-ListA label that is in no label policy exists in the tenant but is not offered to anyone.
Parameters of Get-Label
| Parameter | Use |
|---|---|
| -Identity | Name, display name or GUID of one label |
| -IncludeDetailedLabelActions | Show label actions as detailed properties |
| -SkipValidations | Faster retrieval; Microsoft recommends it when a tenant has more than 1000 labels |
| -ReturnModernLabelScheme | Return labels in the modern label scheme |
Related cmdlets in the same session: New-Label, Set-Label, Remove-Label, New-LabelPolicy, Set-LabelPolicy.
When to use it
Use Get-Label to document a tenant's labelling scheme, to find a label's GUID for a script, DLP rule or Microsoft Graph call, to check the order of labels before adding a new one, and to compare settings between a test and a production tenant. Pair it with Get-LabelPolicy when users report that a label is missing from Office apps: the label must exist and be published to them by a policy.
Requirements
| Requirement | Details |
|---|---|
| Module | ExchangeOnlineManagement 3.x; Windows PowerShell 5.1 or PowerShell 7 |
| Connection | Connect-IPPSSession -UserPrincipalName admin@contoso.com (Security & Compliance, not Exchange Online) |
| Role | A Purview role group that includes sensitivity label management or viewing, such as Information Protection Admin or Compliance Administrator |
Before connecting, or without the role, the cmdlet does not exist in the session and fails as "not recognized", the same way as the retention cmdlets. Connection options are on Connect-IPPSSession.
Reading the output
- Parent and sub-labels. A parent label with sub-labels is a container: users pick a sub-label. Sub-labels carry the parent's GUID in
ParentId, so sort byParentIdandPriorityto rebuild the tree. - Name versus DisplayName. Renaming a label in the Purview portal changes
DisplayName;NameandGuidstay the same, so scripts should reference the GUID. - Priority. The order matters for features that compare labels, such as warnings when a user lowers the classification of a document. Check it before inserting a new label in the middle of the list.
Pitfalls
Label changes made in PowerShell or the portal take time to reach Office apps and services, so a label you just created or published may not appear for users right away. Do not test publication with Get-Label alone: confirm the policy with Get-LabelPolicy -Identity NAME and check its locations and included users or groups. For data loss prevention rules that use labels, see DLP policy cmdlets.
FAQ
Why is Get-Label not recognized after Connect-ExchangeOnline?
Sensitivity label cmdlets live in Security & Compliance PowerShell. Connect with Connect-IPPSSession from the same ExchangeOnlineManagement module; Connect-ExchangeOnline does not import them.
How do I export all labels to a CSV file?
Select the properties you need and export them, for example Get-Label | Select-Object Priority, DisplayName, Name, Guid, ParentId | Export-Csv labels.csv -NoTypeInformation.
Can I see which label a specific document has?
Not with Get-Label: it lists label definitions only. Applied labels show up in the files themselves, in activity explorer and in audit records, for example through Search-UnifiedAuditLog.