dotnetup Tutorial: Manage Multiple.NET SDK Versions Safely

A developer can have one.NET project that requires a specific software development kit (SDK), another that needs a newer release, and a third that must stay on a long-term support version. Installing each version separately is possible, but keeping those installations organized and ensuring the right one is used for each project takes extra work. Microsoft introduced dotnetup in public preview on October 15, 2026, to make installing, tracking, and updating.NET SDKs and runtimes easier. This tutorial walks through its setup, version management, project-specific requirements, and the Windows configuration choice that can disrupt an existing development environment.

What dotnetup changes about managing.NET installations

Traditionally, developers have installed.NET through operating-system package managers, standalone installers, or Microsoft's installation scripts. Those methods remain useful, but they can leave installations in different locations and make it harder to maintain several SDK versions side by side. dotnetup adds a management layer that tracks the versions you request, installs the files in a user-managed location, and updates versions according to the channels you select. A channel is a rule describing which versions an installation should follow, such as the latest stable release or a particular feature band.

The distinction matters because installing a newer SDK is not always the same as deciding that every project should use it. A repository may specify its expected SDK through global.json, a configuration file that helps the.NET command-line tools select a compatible version. dotnetup can use that requirement when managing installations, while also allowing a developer to keep separate versions for other projects. Microsoft currently describes the utility as a public preview, so commands and behaviour may change before a stable release.

Check the operating system and choose an installation mode

The documented preview supports Windows, macOS, and Linux on x64 and Arm64 architectures, with Linux support covering both glibc-based systems and musl-based distributions such as Alpine Linux. You need a terminal and the appropriate shell for the installation method: PowerShell on Windows, or Bash on macOS and Linux. On Unix-like systems, the setup process also requires a download utility such as curl or wget. Before installing, decide how the managed.NET installation should be exposed to your applications, because that choice affects which SDK a command discovers.

Microsoft documents three access modes. The shell mode updates your shell profile so commands launched from that shell use the managed installation; none avoids changing the usual.NET environment and lets you run the managed installation through dotnetup; and everywhere, available on Windows, changes the system path and configures the user-level.NET root. The last option can take precedence over installations used by tools such as Visual Studio. If you are testing the preview on a machine with an established development environment, use shell or none unless you have deliberately planned how to migrate existing installations.

Install dotnetup and verify the first SDK

Use Microsoft's official installation instructions to obtain the appropriate bootstrap script for your operating system. The scripts install a preview build by default and verify the downloaded executable using its SHA-512 checksum. After the executable is available in your environment, start the interactive setup with the following command:

dotnetup init

The setup asks which SDK channel to install and how applications should access the managed installation. For a first test, choose the latest stable SDK channel and an access mode that fits your environment. Read the Windows environment warning carefully before accepting the recommended settings, particularly if Visual Studio or other tools already rely on machine-wide SDK installations. Once setup completes, open a new terminal if the environment settings have changed.

Check that the installation works by running these commands:

dotnetup --version
dotnetup list
dotnet --version

The first command reports the installed dotnetup version, the second lists installations managed by the tool, and the third checks which SDK the ordinary dotnet command resolves. If you selected the none access mode, use dotnetup dotnet -- --version for the managed SDK instead. The extra separator makes it clear that --version belongs to the forwarded.NET command. If the reported version is not the one you expected, inspect the selected access mode and the current project's SDK configuration before installing another version.

Install a stable SDK or track a particular version channel

For a simple non-interactive installation, dotnetup install latest installs the latest stable SDK channel and records that requirement for future management. You can also select channels such as lts for the latest active long-term support SDK, preview for the latest preview SDK, or a specific major version such as 10. More specific channels can target a major and minor release or a feature band, while an exact version pins the installation to that version. This lets a developer choose between following a release line and keeping a fixed SDK for a reproducible environment.

dotnetup install latest
dotnetup list
dotnet --version

Use the output from dotnetup list to confirm which requirement was recorded and which SDK was installed. The actual version resolved by a channel depends on the releases available at installation time, so avoid hard-coding an expected version number into a tutorial or deployment script unless the project truly requires that exact release. A moving channel is convenient for routine updates, but it should not replace deliberate version pinning in build environments where every machine must use the same toolchain.

Use a repository's global.json to select its SDK

When you work across several repositories, the project's own SDK requirement should guide the installation rather than whichever version happens to be newest on your computer. A global.json file can specify a version and a rollForward policy that determines which compatible SDK versions the command-line tools may select. In a repository that already contains this file, run the SDK installation workflow from the repository directory and let dotnetup inspect the nearest configuration. This is safer than assuming that a global installation of the latest SDK will automatically satisfy every project.

For example, a repository might contain the following configuration:

{
 "sdk": {
 "version": "10.0.103",
 "rollForward": "latestPatch"
 }
}

This example pins the requested SDK to version 10.0.103 while allowing the SDK selection policy to move to an eligible later patch version. The actual version chosen depends on the available installations and the configured policy. When a repository has a global.json file, use the documented command without specifying a channel to install the SDK requirement derived from that file:

dotnetup sdk install
dotnetup list

Inspect the list afterward to confirm that the repository requirement has been recorded. This is particularly useful for teams that maintain several applications on different release lines: the tool can keep those requirements organized without forcing every repository to adopt one shared SDK version. Do not edit the project's configuration simply to make a local installation succeed; first establish whether the requested version is intentional and whether the project's compatibility policy permits a newer one.

Update managed SDKs without losing version control

One of dotnetup's main advantages is that it remembers whether an installation follows a moving channel or an exact version. To update tracked SDK and runtime requirements, use dotnetup update. The command resolves eligible channels again, installs newer matching versions when available, and cleans up files that are no longer required by tracked installations. Exact-version requirements are skipped, so a project that deliberately requests a fixed SDK does not silently move to a different version just because an update was run.

dotnetup update
dotnetup list

Review the resulting inventory rather than assuming every update succeeded. The command continues processing other requirements if an individual update fails, then reports failure after processing the remaining items. To update SDK requirements only, use dotnetup sdk update; to include runtime requirements in that operation, add --all. A runtime is the software required to execute a.NET application, whereas the SDK also supplies the tools needed to build and develop one. Keeping those components distinct helps teams avoid installing development tools when they only need a particular runtime, or overlooking a runtime dependency when updating their development environment.

Understand the Windows path warning before migrating

The most important setup risk is not downloading the wrong SDK; it is changing which installation other tools find. In Windows everywhere mode, dotnetup can place its managed installation ahead of machine-wide installations on the system path. A project or application that depends on an SDK or runtime installed by Visual Studio may then fail if that component has not also been installed under dotnetup. This does not mean the original files have necessarily been deleted; it means the environment may resolve a different executable or runtime than it did before.

For a cautious trial, choose shell to limit the change to commands launched from the configured shell, or choose none to keep the existing environment variables untouched and explicitly invoke the managed installation. Check both dotnet --info and the output of dotnetup list when diagnosing a mismatch. If an application stops building after setup, verify the SDK selected for that repository and the environment used by the IDE before changing project files. Teams should test the selected mode on a non-critical machine before rolling it out to developer workstations.

Know what the public preview does not promise yet

dotnetup is a management tool, not a replacement for the full.NET development platform. It does not make an application compatible with a newer SDK, remove the need for tests, or guarantee that updating a machine will patch applications already deployed to users. Self-contained applications, which bundle the runtime they need, may require a fresh publish and deployment to incorporate updated runtime fixes. Build pipelines also need explicit toolchain choices; Microsoft's announcement describes integration with continuous integration and delivery systems such as GitHub Actions and Azure DevOps as future work, not a feature that should be assumed to be complete in the preview.

For a production repository, begin by recording the current SDK version, build result, and test outcome. Install the same requirement with dotnetup, verify the selected version, and rerun the build and tests before changing the project's version policy. Once the process is repeatable, decide which channels should receive routine updates and which projects must remain pinned. That gives your team a controlled way to evaluate the preview without turning a toolchain experiment into an unexpected change across every.NET application on the machine.