skip to content

What is the difference between the .NET SDK and the .NET runtime, and what do dotnet --info, --list-sdks and --list-runtimes show?

level: juniorimportance: must knowfreq 55%

answer

  1. build tools vs run-only
  2. SDK 10.0.4xx, runtime 10.0.x
  3. Microsoft.NETCore.App and Microsoft.AspNetCore.App
  4. feature bands install side by side
  5. dotnet --version honours global.json

basics

~20 s

The .NET SDK is the toolchain (dotnet CLI, MSBuild, compilers, NuGet, templates) used to build apps; the runtime only runs them. dotnet --list-sdks and --list-runtimes print what is installed, and dotnet --info prints both plus the SDK selected for the current folder.

solid answer

~40 s

The **runtime** is what executes an app: `Microsoft.NETCore.App`, plus `Microsoft.AspNetCore.App` for web apps, installed as shared frameworks. The **SDK** is the toolchain behind `dotnet build`, `test` and `publish`: MSBuild, the compilers, NuGet and the templates. Installing an SDK also installs the runtimes of its version, so the 10.0.4xx SDK brings a .NET 10 runtime. SDK versions use **feature bands** (`10.0.1xx`, `10.0.2xx`, `10.0.4xx`) that install side by side, while a newer patch in the same band replaces the older one. `dotnet --list-sdks` and `dotnet --list-runtimes` list installs with their paths, `dotnet --version` prints the SDK that would be used in the current folder (which `global.json` can change), and `dotnet --info` shows that SDK, the installed SDKs and runtimes, and environment details.

code

bash · 9 lines
bash
dotnet --version          # SDK used in this folder (global.json applies)
dotnet --list-sdks        # every installed SDK and its path
dotnet --list-runtimes    # Microsoft.NETCore.App, Microsoft.AspNetCore.App, ...
dotnet --info             # all of the above plus OS, RID, host
dotnet sdk check          # what is out of date per feature band

# CI images: no telemetry, no first-run banner
export DOTNET_CLI_TELEMETRY_OPTOUT=1
export DOTNET_NOLOGO=1

go deeper

for a junior

Recall that the SDK builds and the runtime runs, and that dotnet --list-sdks and --list-runtimes show what is installed.

for a middle

Explain feature bands, why SDKs install side by side, what dotnet --version actually reports, and that a newer SDK builds older target frameworks.

for a senior

Diagnose machine drift: compare dotnet --info across agents, keep runtimes and SDKs out of production images where not needed, and set telemetry and banner variables in CI.

for a principal

Define what a build image and a runtime image contain and how they are patched, so build drift and unpatched runtimes are owned by someone rather than discovered.

## Two different installs .NET ships two kinds of installation, and confusing them is the root of most "works on my machine" build problems: | | SDK | Runtime | |---|---|---| | Purpose | build, test, pack and publish apps | run apps | | Contains | the `dotnet` CLI commands, MSBuild, the C# compiler, NuGet, project templates | shared frameworks such as `Microsoft.NETCore.App` and `Microsoft.AspNetCore.App` | | Version shape | `10.0.4xx`: major, minor, feature band, patch | `10.0.x`: major, minor, patch | | Needed on a server | no, unless you build there | yes, for framework-dependent apps | An SDK installation includes the runtimes of its own version: install the .NET 10 SDK and you also get the .NET 10 runtime and the ASP.NET Core 10 runtime. A server that only runs framework-dependent apps needs just the runtime; a self-contained app needs neither. ## Feature bands The SDK version's third number groups releases into **feature bands**: `10.0.100`-`10.0.199` is the `10.0.1xx` band, `10.0.400`-`10.0.499` the `10.0.4xx` band. A band can bring new MSBuild, NuGet or CLI features, which is why bands install **side by side**, while a patch inside a band replaces the earlier patch of that band. One machine can therefore hold `10.0.1xx` and `10.0.4xx` SDKs at once. ## What the commands show - `dotnet --list-sdks`: every installed SDK version with its folder, for the architecture of the `dotnet` you invoked. - `dotnet --list-runtimes`: every shared framework with its version and folder, such as `Microsoft.NETCore.App 10.0.12` and `Microsoft.AspNetCore.App 10.0.12`. - `dotnet --version`: the version of the SDK that `dotnet` commands **would use in the current directory**. A `global.json` above that directory can select a different SDK than the newest one installed, so this is the first thing to check when two folders build differently. - `dotnet --info`: the selected SDK, the host, all SDKs and runtimes, the OS and RID, and environment variables that affect `dotnet`. It is what you paste into a bug report. - `dotnet sdk check`: the latest available SDK and runtime for each installed feature band, flagging what is out of date. With the .NET 10 host, `--list-sdks` and `--list-runtimes` also accept `--arch` to inspect an install of another architecture. ## Building older targets with a newer SDK The SDK and the target framework are independent. The .NET 10 SDK builds `net8.0` and `net9.0` projects as well as `net10.0`; running or testing them needs the matching runtime. The reverse fails: an older SDK cannot target a newer framework and reports **NETSDK1045** ("The current .NET SDK does not support '...' as a target"). Pinning which SDK a repository uses is the job of `global.json`. ## Telemetry The SDK collects usage telemetry by default in Microsoft builds. Set `DOTNET_CLI_TELEMETRY_OPTOUT` to `1` or `true` to opt out, before installing if you also want the installer's single telemetry event suppressed. `DOTNET_NOLOGO` only hides the first-run banner and does not affect telemetry. CI images usually set both. ## Common mistakes - Installing only a runtime on a build agent and wondering why `dotnet build` is not available. - Reading the runtime version from `--list-runtimes` and assuming it is the SDK version that builds the code. - Assuming the newest SDK always builds the repository when a `global.json` pins another one.

  • Why can dotnet --version print different values in two folders on the same machine?
    It prints the SDK that would be selected for the current directory. A `global.json` in or above one folder can pin an older installed SDK, while the other folder, with no `global.json`, gets the highest installed SDK.
  • Does DOTNET_NOLOGO disable telemetry?
    No. It only hides the welcome and telemetry notice text. Telemetry is turned off with `DOTNET_CLI_TELEMETRY_OPTOUT` set to `1` or `true`.

The SDK is a print shop's workshop with presses and typesetting tools; the runtime is the reader who only needs the finished booklet. You need the workshop to make a booklet, but every reader needs only the booklet and the ability to read it.

  • A production server needs the SDK installed to run a framework-dependent app.
  • The SDK version and the runtime version are always the same number.
  • Installing SDK 10.0.400 removes an installed 10.0.100 SDK.
  • The .NET 10 SDK can only build net10.0 projects.
  • DOTNET_NOLOGO turns off SDK telemetry.