Workloads

This section documents MSBuild 18.9, the .NET SDK 10.0.402 (with its dotnet CLI) and NuGet 7.9, as published in the MSBuild, .NET and NuGet documentation on learn.microsoft.com, which is the reference these pages are written and verified against. Material about .NET 11 / NuGet 8.0 is still in preview and is always flagged as such — never presented as baseline.

This content was generated with the assistance of AI and should be verified against the official documentation before being relied on in production.

The C# Reference bibliography lists the reference material consulted while preparing these pages.

A workload is an optional part of the .NET SDK installed on demand: the toolchains and runtime packs for mobile and desktop platforms (android, ios, maui, macos), WebAssembly (wasm-tools) and WASI (wasi-experimental). Workloads keep the SDK download small while letting it build for platforms most developers never target. .NET Aspire was a workload in .NET 8 and became ordinary NuGet packages and an SDK in .NET 9. This page manages workloads with .NET SDK 10.0.402 on Linux x64, where the platform-specific iOS and Mac Catalyst workloads are not offered.

Finding and installing

dotnet workload search
dotnet workload install wasi-experimental
dotnet workload list

Workload ID                 Description
--------------------------------------------------------------------------------
android                     .NET SDK Workload for building Android applications.
macos                       .NET SDK Workload for building macOS applications.
maui-android                .NET MAUI SDK for Android
maui-tizen                  .NET MAUI SDK for Tizen
maui-windows                .NET MAUI SDK for Windows
wasi-experimental           .NET WASI experimental tooing for net10.0
wasm-experimental           .NET WebAssembly experimental tooling for net10.0
wasm-tools                  .NET WebAssembly build tools for net10.0
wasm-tools-net9             .NET WebAssembly build tools for net9.0
…
Installing pack Microsoft.NETCore.App.Runtime.AOT.linux-x64.Cross.wasi-wasm version 10.0.13...
Writing workload pack installation record for Microsoft.NETCore.App.Runtime.AOT.linux-x64.Cross.wasi-wasm version 10.0.13...
Installing pack Microsoft.NET.Runtime.WebAssembly.Wasi.Sdk version 10.0.13...
…
Garbage collecting for SDK feature band(s) 9.0.300 10.0.400...

Successfully installed workload(s) wasi-experimental.

Workload version: 10.0.402.1

Installed Workload Id      Manifest Version       Installation Source
---------------------------------------------------------------------
wasi-experimental          10.0.113/10.0.100      SDK 10.0.400

A workload is a set of packs — runtime packs, cross-compilers, templates — installed into the dotnet folder (packs/, sdk-manifests/), so installing one into a system-wide .NET needs administrator rights. Workloads are tied to an SDK feature band (10.0.400 above): installing a new band, such as 10.0.500, means installing its workloads again. The "Garbage collecting" step removes packs that no installed band uses.

IDs with a framework suffix (wasm-tools-net9) are the same tooling for older target frameworks.

Source: dotnet workload, dotnet workload search, dotnet workload install.

When a project needs a workload

A project that targets a platform framework without its workload fails at evaluation, with the fix in the message:

<TargetFramework>net10.0-android</TargetFramework>

~/.dotnet/sdk/10.0.402/Sdks/Microsoft.NET.Sdk/targets/Microsoft.NET.Sdk.ImportWorkloads.targets(38,5): error NETSDK1147: To build this project, the following workloads must be installed: android [~/wl/W.csproj]
~/.dotnet/sdk/10.0.402/Sdks/Microsoft.NET.Sdk/targets/Microsoft.NET.Sdk.ImportWorkloads.targets(38,5): error NETSDK1147: To install these workloads, run the following command: dotnet workload restore [~/wl/W.csproj]

dotnet workload restore reads the projects in the current folder (or the one given) and installs every workload they need — the command for CI and new machines.

Source: dotnet workload restore, NETSDK1147.

Maintenance commands

Command Purpose

Command	Purpose
`dotnet workload update`	Update installed workloads (to the newest workload set, or newest manifests; see below).
`dotnet workload repair`	Reinstall missing or damaged packs of installed workloads.
`dotnet workload uninstall <id>`	Remove a workload.
`dotnet workload clean`	Remove packs left behind by uninstalled SDKs or failed operations (`--all` for every band).
`dotnet workload history`	List install/update operations and the workload version after each (.NET 9).
`dotnet workload config --update-mode`	Show or set `workload-set` or `manifests` update mode (8.0.400+).

dotnet workload update

Update installed workloads (to the newest workload set, or newest manifests; see below).

dotnet workload repair

Reinstall missing or damaged packs of installed workloads.

dotnet workload uninstall <id>

Remove a workload.

dotnet workload clean

Remove packs left behind by uninstalled SDKs or failed operations (--all for every band).

dotnet workload history

List install/update operations and the workload version after each (.NET 9).

dotnet workload config --update-mode

Show or set workload-set or manifests update mode (8.0.400+).

dotnet workload history
dotnet workload repair
dotnet workload uninstall wasi-experimental

Id      Date                            Command           Workloads              Global.json Version      Workload Version
-------------------------------------------------------------------------------------------------------------------------------------
1       01/01/0001 00:00:00 +00:00      InitialState                                                      10.0.400-manifests.da132f47
2       10/23/2026 19:28:33 +00:00      install           wasi-experimental                               10.0.402.1

Successfully repaired workloads: wasi-experimental

Successfully uninstalled workload(s): wasi-experimental

The history shows the effect of the first install: before it, the SDK used the workload manifests it shipped with (10.0.400-manifests.da132f47); the install moved the installation to the newest workload set, 10.0.402.1.

Source: dotnet workload history, dotnet workload repair, dotnet workload clean, dotnet workload config, What’s new in the .NET 9 SDK: Workload history.

Workload sets

A workload set is a version number (10.0.402.1) for a group of workload manifests that were released and tested together. In workload-set update mode — the mode this SDK 10.0.402 installation reported — install, update and restore move all workloads to one set at once; in the older manifests mode each workload’s manifest updates independently, which is how two developers ended up with different MAUI versions from the same command.

dotnet workload config --update-mode
dotnet workload search version

workload-set
10.0.402.1
10.0.402
10.0.401.1
10.0.401
10.0.400.1

A repository pins its set in global.json, next to the SDK version, so that dotnet workload restore installs the same set everywhere:

{
  "sdk": {
    "version": "10.0.402",
    "workloadVersion": "10.0.400"
  }
}

10.0.400 (not installed)

Workload version 10.0.400, which was specified in ~/wl3/global.json, was not found. Run "dotnet workload restore" to install this workload version.

(dotnet workload --version and dotnet workload list in that folder.) With a workloadVersion in global.json, the commands use workload-set mode and that set regardless of config; --version on install/update is ignored inside the folder. Advertising manifests — notices of newer manifests that dotnet workload update downloads in the background — tell the CLI when an update is available.

Source: Workload sets, Use global.json for the workload-set version, Check the update mode and version, dotnet workload install: Advertising manifests, What’s new in the .NET 9 SDK: Workload sets.

Common mistakes

Installing workloads by hand on build agents — run dotnet workload restore in the repository instead.
Upgrading the SDK band and expecting workloads to follow — each band needs its own install.
Mixing update modes across a team — pin workloadVersion in global.json.
Running workload commands without rights to the dotnet folder — a system-wide installation needs sudo or an elevated prompt.