.NET environment variables
This article applies to: ✔️ .NET Core 3.1 SDK and later versions
In this article, you'll learn about the environment variables used by .NET. Some environment variables are used by the .NET runtime, while others are only used by the .NET SDK and .NET CLI. Some environment variables are used by all three components.
.NET runtime environment variables
DOTNET_SYSTEM_NET_HTTP_*
There are several global HTTP environment variable settings:
DOTNET_SYSTEM_NET_HTTP_ENABLEACTIVITYPROPAGATION
- Indicates whether or not to enable activity propagation of the diagnostic handler for global HTTP settings.
DOTNET_SYSTEM_NET_HTTP_SOCKETSHTTPHANDLER_HTTP2SUPPORT
- When set to
false
or0
, disables HTTP/2 support, which is enabled by default.
- When set to
DOTNET_SYSTEM_NET_HTTP_SOCKETSHTTPHANDLER_HTTP3SUPPORT
- When set to
true
or1
, enables HTTP/3 support, which is disabled by default.
- When set to
DOTNET_SYSTEM_NET_HTTP_SOCKETSHTTPHANDLER_HTTP2FLOWCONTROL_DISABLEDYNAMICWINDOWSIZING
- When set to
false
or0
, overrides the default and disables the HTTP/2 dynamic window scaling algorithm.
- When set to
DOTNET_SYSTEM_NET_HTTP_SOCKETSHTTPHANDLER_FLOWCONTROL_MAXSTREAMWINDOWSIZE
- Defaults to 16 MB. When overridden, the maximum size of the HTTP/2 stream receive window cannot be less than 65,535.
DOTNET_SYSTEM_NET_HTTP_SOCKETSHTTPHANDLER_FLOWCONTROL_STREAMWINDOWSCALETHRESHOLDMULTIPLIER
- Defaults to 1.0. When overridden, higher values result in a shorter window but slower downloads. Can't be less than 0.
DOTNET_SYSTEM_GLOBALIZATION_*
DOTNET_SYSTEM_GLOBALIZATION_INVARIANT
: See set invariant mode.DOTNET_SYSTEM_GLOBALIZATION_PREDEFINED_CULTURES_ONLY
: Specifies whether to load only predefined cultures.DOTNET_SYSTEM_GLOBALIZATION_APPLOCALICU
: Indicates whether to use the app-local International Components of Unicode (ICU). For more information, see App-local ICU.
Set invariant mode
Applications can enable the invariant mode in any of the following ways:
In the project file:
<PropertyGroup> <InvariantGlobalization>true</InvariantGlobalization> </PropertyGroup>
In the runtimeconfig.json file:
{ "runtimeOptions": { "configProperties": { "System.Globalization.Invariant": true } } }
By setting environment variable value
DOTNET_SYSTEM_GLOBALIZATION_INVARIANT
totrue
or1
.
Important
A value set in the project file or runtimeconfig.json has a higher priority than the environment variable.
For more information, see .NET Globalization Invariant Mode.
DOTNET_SYSTEM_GLOBALIZATION_USENLS
This applies to Windows only. For globalization to use National Language Support (NLS), set DOTNET_SYSTEM_GLOBALIZATION_USENLS
to either true
or 1
. To not use it, set DOTNET_SYSTEM_GLOBALIZATION_USENLS
to either false
or 0
.
DOTNET_SYSTEM_NET_SOCKETS_*
This section focuses on two System.Net.Sockets
environment variables:
DOTNET_SYSTEM_NET_SOCKETS_INLINE_COMPLETIONS
DOTNET_SYSTEM_NET_SOCKETS_THREAD_COUNT
Socket continuations are dispatched to the System.Threading.ThreadPool from the event thread. This avoids continuations blocking the event handling. To allow continuations to run directly on the event thread, set DOTNET_SYSTEM_NET_SOCKETS_INLINE_COMPLETIONS
to 1
. It's disabled by default.
Note
This setting can make performance worse if there is expensive work that will end up holding onto the IO thread for longer than needed. Test to make sure this setting helps performance.
Using TechEmpower benchmarks that generate a lot of small socket reads and writes under a very high load, a single socket engine is capable of keeping busy up to thirty x64 and eight Arm64 CPU cores. The vast majority of real-life scenarios will never generate such a huge load (hundreds of thousands of requests per second),
and having a single producer is almost always enough. However, to be sure that extreme loads can be handled, you can use DOTNET_SYSTEM_NET_SOCKETS_THREAD_COUNT
to override the calculated value. When not overridden, the following value is used:
- When
DOTNET_SYSTEM_NET_SOCKETS_INLINE_COMPLETIONS
is1
, the Environment.ProcessorCount value is used. - When
DOTNET_SYSTEM_NET_SOCKETS_INLINE_COMPLETIONS
is not1
, RuntimeInformation.ProcessArchitecture is evaluated:- When Arm or Arm64 the cores per engine value is set to
8
, otherwise30
.
- When Arm or Arm64 the cores per engine value is set to
- Using the determined cores per engine, the maximum value of either
1
or Environment.ProcessorCount over the cores per engine.
DOTNET_SYSTEM_NET_DISABLEIPV6
Helps determine whether or not Internet Protocol version 6 (IPv6) is disabled. When set to either true
or 1
, IPv6 is disabled unless otherwise specified in the System.AppContext.
DOTNET_SYSTEM_NET_HTTP_USESOCKETSHTTPHANDLER
You can use one of the following mechanisms to configure a process to use the older HttpClientHandler
:
From code, use the AppContext
class:
AppContext.SetSwitch("System.Net.Http.UseSocketsHttpHandler", false);
The AppContext
switch can also be set by a config file. For more information configuring switches, see AppContext for library consumers.
The same can be achieved via the environment variable DOTNET_SYSTEM_NET_HTTP_USESOCKETSHTTPHANDLER
. To opt-out, set the value to either false
or 0
.
Note
Starting in .NET 5, this setting to use HttpClientHandler is no longer available.
DOTNET_Jit*
and DOTNET_GC*
There are two stressing-related features for the JIT and JIT-generated GC information: JIT Stress and GC Hole Stress. These features provide a way during development to discover edge cases and more "real world" scenarios without having to develop complex applications. The following environment variables are available:
DOTNET_JitStress
DOTNET_JitStressModeNamesOnly
DOTNET_GCStress
JIT stress
Enabling JIT Stress can be done in several ways. Set DOTNET_JitStress
to a non-zero integer value to generate varying levels of JIT optimizations based on a hash of the method's name. To apply all optimizations set DOTNET_JitStress=2
, for example. Another way to enable JIT Stress is by setting DOTNET_JitStressModeNamesOnly=1
and then requesting the stress modes, space-delimited, in the DOTNET_JitStressModeNames
variable.
As an example, consider:
DOTNET_JitStressModeNames=STRESS_USE_CMOV STRESS_64RSLT_MUL STRESS_LCL_FLDS
GC Hole stress
Enabling GC Hole Stress causes GCs to always occur in specific locations and that helps to track down GC holes. GC Hole Stress can be enabled using the DOTNET_GCStress
environment variable.
For more information, see Investigating JIT and GC Hole stress.
JIT memory barriers
The code generator for Arm64 allows all MemoryBarriers
instructions to be removed by setting DOTNET_JitNoMemoryBarriers
to 1
.
DOTNET_RUNNING_IN_CONTAINER
and DOTNET_RUNNING_IN_CONTAINERS
The official .NET images (Windows and Linux) set the well-known environment variables:
DOTNET_RUNNING_IN_CONTAINER
DOTNET_RUNNING_IN_CONTAINERS
These values are used to determine when your ASP.NET Core workloads are running in the context of a container.
DOTNET_SYSTEM_CONSOLE_ALLOW_ANSI_COLOR_REDIRECTION
When Console.IsOutputRedirected is true
, you can emit ANSI color code by setting DOTNET_SYSTEM_CONSOLE_ALLOW_ANSI_COLOR_REDIRECTION
to either 1
or true
.
DOTNET_SYSTEM_DIAGNOSTICS
and related variables
DOTNET_SYSTEM_DIAGNOSTICS_DEFAULTACTIVITYIDFORMATISHIERARCHIAL
: When1
ortrue
, the default Activity Id format is hierarchical.DOTNET_SYSTEM_RUNTIME_CACHING_TRACING
: When running as Debug, tracing can be enabled when this istrue
.
DOTNET_DiagnosticPorts
Configures alternate endpoints where diagnostic tools can communicate with the .NET runtime. See the Diagnostic Port documentation for more information.
DOTNET_DefaultDiagnosticPortSuspend
Configures the runtime to pause during startup and wait for the Diagnostics IPC ResumeStartup command from the specified diagnostic port when set to 1. Defaults to 0. See the Diagnostic Port documentation for more information.
DOTNET_EnableDiagnostics
When set to 0
, disables debugging, profiling, and other diagnostics via the Diagnostic Port and can't be overridden by other diagnostics settings. Defaults to 1
.
DOTNET_EnableDiagnostics_IPC
Starting with .NET 8, when set to 0
, disables the Diagnostic Port and can't be overridden by other diagnostics settings. Defaults to 1
.
DOTNET_EnableDiagnostics_Debugger
Starting with .NET 8, when set to 0
, disables debugging and can't be overridden by other diagnostics settings. Defaults to 1
.
DOTNET_EnableDiagnostics_Profiler
Starting with .NET 8, when set to 0
, disables profiling and can't be overridden by other diagnostics settings. Defaults to 1
.
EventPipe variables
See EventPipe environment variables for more information.
DOTNET_EnableEventPipe
: When set to1
, enables tracing via EventPipe.DOTNET_EventPipeOutputPath
: The output path where the trace will be written.DOTNET_EventPipeOutputStreaming
: When set to1
, enables streaming to the output file while the app is running. By default trace information is accumulated in a circular buffer and the contents are written at app shutdown.
.NET SDK and CLI environment variables
DOTNET_ROOT
, DOTNET_ROOT(x86)
, DOTNET_ROOT_X86
, DOTNET_ROOT_X64
Specifies the location of the .NET runtimes, if they are not installed in the default location. The default location on Windows is C:\Program Files\dotnet
. The default location on macOS is /usr/local/share/dotnet
. The default location for the x64 runtimes on an arm64 OS is under an x64 subfolder (so C:\Program Files\dotnet\x64
on windows and /usr/local/share/dotnet/x64
on macOS. The default location on Linux varies depending on distro and installment method. The default location on Ubuntu 22.04 is /usr/share/dotnet
(when installed from packages.microsoft.com
) or /usr/lib/dotnet
(when installed from Jammy feed). For more information, see the following resources:
- Troubleshoot app launch failures
- GitHub issue dotnet/core#7699
- GitHub issue dotnet/runtime#79237
This environment variable is used only when running apps via generated executables (apphosts). DOTNET_ROOT(x86)
is used instead when running a 32-bit executable on a 64-bit OS. DOTNET_ROOT_X64
is used instead when running a 64-bit executable on an ARM64 OS.
DOTNET_HOST_PATH
Specifies the absolute path to a dotnet
host (dotnet.exe
on Windows, dotnet
on Linux and macOS) that was used to launch the currently-running dotnet
process. This is used by the .NET SDK to help tools that run during .NET SDK commands ensure they use the same dotnet
runtime for any child dotnet
processes they create for the duration of the command. Tools and MSBuild Tasks within the SDK that invoke binaries via the dotnet
host are expected to honor this environment variable to ensure a consistent experience.
Tools that invoke dotnet
during an SDK command should use the following algorithm to locate it:
- if
DOTNET_HOST_PATH
is set, use that value directly - otherwise, rely on
dotnet
via the system'sPATH
Note
DOTNET_HOST_PATH
is not a general solution for locating the dotnet
host. It is only intended to be used by tools that are invoked by the .NET SDK.
DOTNET_LAUNCH_PROFILE
The dotnet run command sets this variable to the selected launch profile.
Given the following launchSettings.json file:
{
"profiles": {
"First": {
"commandName": "Project",
},
"Second": {
"commandName": "Project",
}
}
}
And the following Program.cs file:
var value = Environment.GetEnvironmentVariable("DOTNET_LAUNCH_PROFILE");
Console.WriteLine($"DOTNET_LAUNCH_PROFILE={value}");
The following scenarios produce the output shown:
Launch profile specified and exists
$ dotnet run --launch-profile First DOTNET_LAUNCH_PROFILE=First
Launch profile not specified, first one selected
$ dotnet run DOTNET_LAUNCH_PROFILE=First
Launch profile specified but does not exist
$ dotnet run --launch-profile Third The launch profile "Third" could not be applied. A launch profile with the name 'Third' doesn't exist. DOTNET_LAUNCH_PROFILE=
Launch with no profile
$ dotnet run --no-launch-profile DOTNET_LAUNCH_PROFILE=
NUGET_PACKAGES
The global packages folder. If not set, it defaults to ~/.nuget/packages
on Unix or %userprofile%\.nuget\packages
on Windows.
DOTNET_SERVICING
Specifies the location of the servicing index to use by the shared host when loading the runtime.
DOTNET_NOLOGO
Specifies whether .NET welcome and telemetry messages are displayed on the first run. Set to true
to mute these messages (values true
, 1
, or yes
accepted) or set to false
to allow them (values false
, 0
, or no
accepted). If not set, the default is false
and the messages will be displayed on the first run. This flag does not affect telemetry (see DOTNET_CLI_TELEMETRY_OPTOUT
for opting out of sending telemetry).
DOTNET_CLI_PERF_LOG
Specifies whether performance details about the current CLI session are logged. Enabled when set to 1
, true
, or yes
. This is disabled by default.
DOTNET_GENERATE_ASPNET_CERTIFICATE
Specifies whether to generate an ASP.NET Core certificate. The default value is true
, but this can be overridden by setting this environment variable to either 0
, false
, or no
.
DOTNET_ADD_GLOBAL_TOOLS_TO_PATH
Specifies whether to add global tools to the PATH
environment variable. The default is true
. To not add global tools to the path, set to 0
, false
, or no
.
DOTNET_CLI_TELEMETRY_OPTOUT
Specifies whether data about the .NET tools usage is collected and sent to Microsoft. Set to true
to opt-out of the telemetry feature (values true
, 1
, or yes
accepted). Otherwise, set to false
to opt into the telemetry features (values false
, 0
, or no
accepted). If not set, the default is false
and the telemetry feature is active.
DOTNET_SKIP_FIRST_TIME_EXPERIENCE
If DOTNET_SKIP_FIRST_TIME_EXPERIENCE
is set to true
, the NuGetFallbackFolder
won't be expanded to disk and a shorter welcome message and telemetry notice will be shown.
Note
This environment variable is no longer supported in .NET Core 3.0 and later.
Use DOTNET_NOLOGO
as a replacement.
DOTNET_MULTILEVEL_LOOKUP
Specifies whether the .NET runtime, shared framework, or SDK are resolved from the global location. If not set, it defaults to 1 (logical true
). Set the value to 0 (logical false
) to not resolve from the global location and have isolated .NET installations. For more information about multi-level lookup, see Multi-level SharedFX Lookup.
Note
This environment variable only applies to applications that target .NET 6 and earlier versions. Starting in .NET 7, .NET only looks for frameworks in one location. For more information, see Multi-level lookup is disabled.
DOTNET_ROLL_FORWARD
Determines roll forward behavior. For more information, see the --roll-forward
option for the dotnet
command.
DOTNET_ROLL_FORWARD_TO_PRERELEASE
If set to 1
(enabled), enables rolling forward to a pre-release version from a release version. By default (0
- disabled), when a release version of .NET runtime is requested, roll-forward will only consider installed release versions.
For more information, see the --roll-forward
option for the dotnet
command
DOTNET_ROLL_FORWARD_ON_NO_CANDIDATE_FX
Disables minor version roll forward, if set to 0
. This setting is superseded in .NET Core 3.0 by DOTNET_ROLL_FORWARD
. The new settings should be used instead.
DOTNET_CLI_FORCE_UTF8_ENCODING
Forces the use of UTF-8 encoding in the console, even for older versions of Windows 10 that don't fully support UTF-8. For more information, see SDK no longer changes console encoding when finished.
DOTNET_CLI_UI_LANGUAGE
Sets the language of the CLI UI using a locale value such as en-us
. The supported values are the same as for Visual Studio. For more information, see the section on changing the installer language in the Visual Studio installation documentation. The .NET resource manager rules apply, so you don't have to pick an exact match—you can also pick descendants in the CultureInfo
tree. For example, if you set it to fr-CA
, the CLI will find and use the fr
translations. If you set it to a language that is not supported, the CLI falls back to English.
DOTNET_DISABLE_GUI_ERRORS
For GUI-enabled generated executables - disables dialog popup, which normally shows for certain classes of errors. It only writes to stderr
and exits in those cases.
DOTNET_ADDITIONAL_DEPS
Equivalent to CLI option --additional-deps
.
DOTNET_RUNTIME_ID
Overrides the detected RID.
DOTNET_SHARED_STORE
Location of the "shared store" which assembly resolution falls back to in some cases.
DOTNET_STARTUP_HOOKS
List of assemblies to load and execute startup hooks from.
DOTNET_BUNDLE_EXTRACT_BASE_DIR
Specifies a directory to which a single-file application is extracted before it is executed.
For more information, see Single-file executables.
DOTNET_CLI_HOME
Specifies the location that supporting files for .NET CLI commands should be written to. For example:
- User-writable paths for workload packs, manifests, and other supporting data.
- First-run sentinel/lock files for aspects of the .NET CLI's first-run migrations and notification experiences.
- The default .NET local tool installation location.
DOTNET_CLI_CONTEXT_*
DOTNET_CLI_CONTEXT_VERBOSE
: To enable a verbose context, set totrue
.DOTNET_CLI_CONTEXT_ANSI_PASS_THRU
: To enable an ANSI pass-through, set totrue
.
DOTNET_CLI_WORKLOAD_UPDATE_NOTIFY_DISABLE
Disables background download of advertising manifests for workloads. Default is false
- not disabled. If set to true
, downloading is disabled. For more information, see Advertising manifests.
DOTNET_CLI_WORKLOAD_UPDATE_NOTIFY_INTERVAL_HOURS
Specifies the minimum number of hours between background downloads of advertising manifests for workloads. The default is 24
, which is no more frequently than once a day. For more information, see Advertising manifests.
DOTNET_TOOLS_ALLOW_MANIFEST_IN_ROOT
Specifies whether .NET SDK local tools search for tool manifest files in the root folder on Windows. The default is false
.
COREHOST_TRACE
Controls diagnostics tracing from the hosting components, such as dotnet.exe
, hostfxr
, and hostpolicy
.
COREHOST_TRACE=[0/1]
- default is0
- tracing disabled. If set to1
, diagnostics tracing is enabled.COREHOST_TRACEFILE=<file path>
- has an effect only if tracing is enabled by settingCOREHOST_TRACE=1
. When set, the tracing information is written to the specified file; otherwise, the trace information is written tostderr
.COREHOST_TRACE_VERBOSITY=[1/2/3/4]
- default is4
. The setting is used only when tracing is enabled viaCOREHOST_TRACE=1
.4
- all tracing information is written3
- only informational, warning, and error messages are written2
- only warning and error messages are written1
- only error messages are written
The typical way to get detailed trace information about application startup is to set COREHOST_TRACE=1
andCOREHOST_TRACEFILE=host_trace.txt
and then run the application. A new file host_trace.txt
will be created in the current directory with the detailed information.
SuppressNETCoreSdkPreviewMessage
If set to true
, invoking dotnet
won't produce a warning when a preview SDK is being used.
Configure MSBuild in the .NET CLI
To execute MSBuild out-of-process, set the DOTNET_CLI_RUN_MSBUILD_OUTOFPROC
environment variable to either 1
, true
, or yes
. By default, MSBuild will execute in-proc. To force MSBuild to use an external working node long-living process for building projects, set DOTNET_CLI_USE_MSBUILDNOINPROCNODE
to 1
, true
, or yes
. This will set the MSBUILDNOINPROCNODE
environment variable to 1
, which is referred to as MSBuild Server V1, as the entry process forwards most of the work to it.
DOTNET_MSBUILD_SDK_RESOLVER_*
These are overrides that are used to force the resolved SDK tasks and targets to come from a given base directory and report a given version to MSBuild, which may be null
if unknown. One key use case for this is to test SDK tasks and targets without deploying them by using the .NET Core SDK.
DOTNET_MSBUILD_SDK_RESOLVER_SDKS_DIR
: Overrides the .NET SDK directory.DOTNET_MSBUILD_SDK_RESOLVER_SDKS_VER
: Overrides the .NET SDK version.DOTNET_MSBUILD_SDK_RESOLVER_CLI_DIR
: Overrides the dotnet.exe directory path.
DOTNET_NEW_PREFERRED_LANG
Configures the default programming language for the dotnet new
command when the -lang|--language
switch is omitted. The default value is C#
. Valid values are C#
, F#
, or VB
. For more information, see dotnet new.
dotnet watch
environment variables
For information about dotnet watch
settings that are available as environment variables, see dotnet watch environment variables.