How to Use Set-MgUserPhotoContent in Powershell

Managing user photos in Microsoft 365 has changed significantly in recent years. Microsoft has moved profile photo storage away from Exchange Online to Microsoft Entra ID, providing a unified experience across Outlook, Teams, and other M365 services. To support this shift, administrators must now use Microsoft Graph PowerShell cmdlets such as Set-MgUserPhotoContent instead of older Exchange Online ones.

The Set-UserPhoto, Get-UserPhoto, and Remove-UserPhoto cmdlets were officially deprecated in Exchange Onlineas announced in Microsoft Tech Community’s deprecation notice.

Microsoft encourages all administrators to transition to Microsoft Graph PowerShell, where Set-MgUserPhotoContent provides a modern, consistent way to upload and manage user profile photos.

What is the Set-MgUserPhotoContent Cmdlet?

The Set-MgUserPhotoContent cmdlet in the Microsoft.Graph.Users module allows administrators and applications to upload or update the photo content of a Microsoft 365 user. It sets the binary media stream (such as a JPG or PNG file) for a user’s profile picture stored in Entra ID, which is automatically displayed across Outlook, Teams, Delve, and other M365 workloads.

This cmdlet is part of the Microsoft Graph PowerShell SDK (also known as MSGraph PowerShell), which uses REST-based calls to the Graph API for managing user, group, and organizational data.

Administrators can specify either a UserId or UserPrincipalName to identify the target account and use the InFile parameter to supply the image file path.

Syntax

Set-MgUserPhotoContent

-UserId <String>

[-InFile <String>]

[-Confirm]

[-PassThru]

[-WhatIf]

Parameters

• UserId – Specifies the unique identifier of the user (can be a GUID, UserPrincipalName, or user ID).
• InFile – Defines the path to the photo file (e.g., C:PhotosUser1.jpg). The file is uploaded as the new profile photo.
• InputObject – Accepts a user object piped from another cmdlet such as Get-MgUser.
• BodyParameter – Allows a photo to be provided as a System.IO.Stream or byte array when uploading programmatically (for example, from an HRIS API).
• Confirm – Prompts for confirmation before executing the operation.
• PassThru – Returns an object representing the updated photo after the operation completes.
• WhatIf – Simulates the operation to preview the result without making any changes.
  

All parameter combinations must include either UserId or InputObject. One of InFile or BodyParameter must be specified to provide the photo data.

Practical Uses

1. Bulk Updating User Photos in Microsoft 365

Large organizations often maintain thousands of employee photos in an HRIS or directory service. Using Set-MgUserPhotoContent with a CSV file, administrators can loop through each user’s UserPrincipalName and automatically upload the correct image.

This ensures consistent and up-to-date user profile photos across all Microsoft 365 services, including Teams, Outlook, and Delve.

2. Standardizing Profile Photos for Compliance or Branding

HR or communications teams may require consistent image dimensions or background colors for internal directories. This cmdlet helps administrators enforce visual consistency by programmatically applying approved photo templates. When paired with Get-MgUserPhotoContent, it can also verify existing photo quality or dimensions.

3. Automating Photo Uploads via Service Principals or Applications

Developers integrating with HRIS APIs can use Set-MgUserPhotoContent with application permissions like User.ReadWrite.All or ProfilePhoto.ReadWrite.All.

This allows an app or service principal (authenticated using a client secret or certificate) to automatically synchronize employee photos from external sources into Microsoft Entra ID, ensuring profile management remains centralized.

Prerequisites

Before using Set-MgUserPhotoContent, confirm the following prerequisites are met:

• Microsoft.Graph.Users module is installed.
  Install by running:
  Install-Module Microsoft.Graph.Users
  
• Required permissions:
• Delegated: User.ReadWrite or ProfilePhoto.ReadWrite.All
• Application: User.ReadWrite.All or ProfilePhoto.ReadWrite.All
  
• Role requirements:
• Global administrator or User administrator roles typically required for tenant-wide changes.
  
• Authentication:
  Use Connect-MgGraph before running the cmdlet. Example:
  Connect-MgGraph -Scopes "User.ReadWrite.All"
  
• File requirements:
• Supported formats: JPG, JPEG, PNG, GIF, BMP
• Recommended dimensions: 648x648 pixels for best display in Teams and Outlook
• File size limit: 4 MB or less
  
• Optional environment settings:
• Ensure proxy configuration is correct when running behind corporate firewalls.
• If using automation, service principals must have valid client ID and secret or certificate credentials registered in Entra ID.
  

How to Use Set-MgUserPhotoContent

1. Upload a Single User Photo

1. Connect to Microsoft Graph PowerShell:
Connect-MgGraph -Scopes "User.ReadWrite.All"

2. Run the cmdlet to upload a photo:

Set-MgUserPhotoContent -UserId james@meetingroom365.com -InFile "C:ImagesUserPhoto.jpg"

This updates the profile photo for the user with the specified UserPrincipalName. The image will sync automatically across Teams, Outlook, and other Microsoft 365 services.

2. Bulk Update User Photos Using a CSV File

To update photos for multiple users stored in a CSV file:

1. Prepare a CSV with columns UserPrincipalName and PhotoPath.

2. Import and loop through each entry

Import-Csv "C:photosusers.csv" | ForEach-Object {
Set-MgUserPhotoContent -UserId $.UserPrincipalName -InFile $.PhotoPath
}

This method is frequently used by administrators or HR teams to perform organization-wide updates after onboarding or photo policy changes.

3. Update User Photos Using an Application (Service Principal)

For automation scenarios, applications or background jobs can use app-based authentication to set photos:

1. Create an Entra ID app registration with the following permissions: User.ReadWrite.All and ProfilePhoto.ReadWrite.All

2. Authenticate with client credentials:

Connect-MgGraph -ClientId "your-client-id" -TenantId "your-tenant-id" -ClientSecret "your-secret"

3. Upload the photo using the same cmdlet:

Set-MgUserPhotoContent -UserId "james@meetingroom365.com" -InFile "C:photosjames.jpg"

This allows the process to run without manual login, ideal for nightly synchronization from HR systems or third-party directories.

Final Note

The Set-MgUserPhotoContent cmdlet is the modern, supported method for managing Microsoft 365 user photos in PowerShell.

It replaces the now-deprecated Set-UserPhoto cmdlet from Exchange Online and provides full compatibility with Microsoft Entra ID and Graph-based profile management.

Whether you need to update a single profile photo or automate large-scale synchronization through an API, this Microsoft Graph PowerShell cmdlet gives administrators and developers precise, secure control over user identity visuals across the entire Microsoft 365 ecosystem.

FAQs

1. Can I use Set-MgUserPhotoContent to update photos for guest users in Microsoft 365?

No, guest users (also known as external users) typically do not have writable photo attributes in Microsoft Entra ID. The Set-MgUserPhotoContent cmdlet applies only to internal accounts within the tenant that have the necessary permissions to modify their profile attributes.

2. What happens if I upload a photo larger than 4 MB or with unsupported dimensions?

If the image exceeds 4 MB or uses an unsupported format, the cmdlet will fail with an error. Microsoft Graph enforces both file size and format restrictions for profile photos. It’s best to resize or compress images before uploading and to use standard square dimensions such as 648x648 pixels.

3. Is it possible to remove a user photo using Set-MgUserPhotoContent?

No, this cmdlet can only upload or replace an existing photo. To remove a user’s profile photo, you must use the Remove-MgUserPhoto cmdlet, which deletes the stored image and resets the user to the default Microsoft 365 avatar.