Upgrade to the new Teams using policies

• Applies to:

  Microsoft Teams

You can upgrade to the new Teams client to your organization by setting policies in either the Teams Admin Center or by using PowerShell.

Prerequisites

Requirement	Version
Windows	Windows 10 version 10.0.19041 or higher (excluding Windows 10 LTSC for Teams desktop app)
Webview2	Update to the most current version. Learn more: Enterprise management of WebView2 Runtimes
Teams app	Version 1.6.00.4472 to see the Try the new Teams toggle. If you are at a lower version, select the overflow menu (…) > Check for updates > Update. Then restart your app.
Settings	Turn on the "Show Notification Banners" setting in System > Notifications > Microsoft Teams to receive Teams Notifications.
Delivery optimization (DO)	DO powers Teams automatic updates, which are required as part of the Servicing Agreement. Overview: What is Delivery Optimization? Recommended settings: Set up Delivery Optimization Note: Download Mode 100 (Bypass) is not supported.

Required Microsoft 365 Apps Security Updates

Channel	Version & Build
Semi-Annual Enterprise Channel	Version 2302 (Build 16130.20306) Version 2208 (Build 15601.20578)
Monthly Enterprise Channel	Version 2301 (Build 16026.20222) Version2212 (Build 15928.20294)
Office LTSB	Version 2018 (Build 10396.20023) Version 2021 (Build 14332.20481)

Learn more at Update History for Microsoft 365 Apps.

Set the policies to upgrade to the new Teams client

As an admin, you can manage how new Teams to your users.

To control which users can see the toggle, use the Teams admin setting UseNewTeamsClient under the TeamsUpdateManagement policy.

Manage this setting in the Teams Admin Center or using Teams PowerShell.

Teams Admin Center

Configure setting via Teams Admin Center.

Policy settings for upgrade

Setting	Description
Not enabled	Use this value to hide the new Teams toggle switch. Users won't be able to opt in to the new Teams.
Classic Teams as default	Use this value to have classic Teams the default version. The new Teams toggle switch displays to let users opt into the new Teams and switch back if needed. Note: This option was previously called Users can choose.
Microsoft controlled	Default. The value lets Microsoft control whether the new Teams toggle switch is shown or not based on product readiness
**New Teams as default Rollout for the feature began in early August, 2023	Use this value to make new Teams as the default version. Users can switch back to classic Teams using the toggle.

In addition to PowerShell, you can also use Teams Admin Center to manage the visibility of the toggle on a per-user basis.

1. Sign in to the Microsoft Teams admin center.

2. Select Teams > Teams Update policies from the left navigation pane.

3. Select Add to create a new policy or select an existing policy to open Update policy.

4. Name the update policy, add a description, and select the setting for “Use new Teams client”, as shown below.

   

Setting	Description
Not enabled	Use this value to hide the new Teams toggle switch. Users won't be able to opt in to the new Teams.
Classic Teams as default	Use this value to have classic Teams the default version. The new Teams toggle switch displays to let users opt into the new Teams and switch back if needed. Note: This option was previously called Users can choose.
New Teams as default	Sets the new Teams as default. Note: This option is currently being rolled out
Microsoft controlled	Default. Use this value to let Microsoft control the following: -Whether the "Try the new Teams" toggle switch is shown or not - In the future, let Microsoft manage the installation of the new Teams client and Allow Microsof to determine default client behavior based on the rollout schedule.

Note

The option "Classic Teams as default" was previously called "Users can choose".

5. Select new Teams as default from this setting to ensure users can get the new Teams experience when they launch

6. Once the policy is defined, you can assign it to a user or user group with the Group policy assignment. To assign it to a group, select Group policy assignment and then Add, or select one of the groups listed.

Select a policy to assign to the group.

7. Once the policy is defined, you can assign it to a specific user under Users> Manage users.

If you update the policy setting in the Teams Admin Center, the new setting can take up to 24 hours to go into effect. The user doesn't have to restart the app.

PowerShell

Configure the UseNewTeamsClient setting to one of the following possible values:

Setting	Explanation
MicrosoftChoice	Default setting. This value lets Microsoft control if the Teams (preview) toggle switch is shown based on product readiness.
User choice	This value lets the new Teams toggle switch display to all users. Users can choose to opt in or out.
AdminDisabled	This value hides the new Teams toggle switch from view. Users won't be able to opt in to the new Teams.

Here are the steps needed to configure this setting in PowerShell:

1. Import the latest Teams PowerShell cmdlets (require version 4.9.1 or greater) by following Manage Teams with Microsoft Teams PowerShell instructions. Direct link: PowerShell Gallery Microsoft Teams 4.9.1.
2. Connect to an admin account using this command:

Connect-MicrosoftTeams

3. Once connected and logged in via PowerShell, you can explore the list of related commands: Enter *-CsTeamsUpdateManagementPolicy and tab through the commands (tab key).

4. Use the following commands to change the existing Update Management policy to opt in the assigned users to allow them to try the new Teams:

Set-CsTeamsUpdateManagementPolicy -identity <new_policy_name> -UseNewTeamsClient 

UserChoice

Example:

Set-CsTeamsUpdateManagementPolicy -identity MySetting -UseNewTeamsClient UserChoice

Note

This method for existing policy modification doesn't take effect immediately. Allow up to 24 hours for the change to propagate to users. Users don't need to restart the app, but specifically for opt-in, they'll need one restart following a fresh install to see the toggle.

5. Use the following commands to deploy a new policy to opt-out a specific user from seeing the toggle:

New-CsTeamsUpdateManagementPolicy -identity <new_policy_name> -UseNewTeamsClient AdminDisabled

Grant-CsTeamsUpdateManagementPolicy -identity <user> -PolicyName <new_policy_name>

Example:

New-CsTeamsUpdateManagementPolicy -identity MySetting -UseNewTeamsClient AdminDisabled
Grant-CsTeamsUpdateManagementPolicy -identity admin@contoso.org -PolicyName MySetting

Note

Allow up to 24 hours for the new policy assignment method to go into effect. Users don't need to restart the app.

How to uninstall the new Teams client

Any user who was using the new Teams before the policy was implemented can manually opt out by using the new Teams toggle.

After they opt out, the toggle won't appear when they relaunch Teams. To prevent users from using this client and want to uninstall the client, users can manually uninstall it from settings.

Remove new Teams for all users

To remove the new Teams from all users' computers, use the following PowerShell command:

Remove-AppxPackage 

PowerShell cmdlet to remove new Teams from all users on all computers:

Get-AppxPackage MSTeams -AllUsers |Remove-AppxPackage -AllUsers For an individual user without administrator privilege, use this command: Get-AppxPackage MSTeams|Remove-AppxPackage