Windows Environment Variables: setx, set & PowerShell

Windows gives you three different mechanisms for environment variables: set (cmd, current session only), setx (persistent, but silently truncates values at 1,024 characters), and PowerShell's $env: drive plus the [Environment] .NET API. Pick the wrong one and the standard outcomes are a variable that vanishes when the window closes — or a destroyed PATH: setx PATH merges the system and user paths, cuts the result at 1,024 characters, prints SUCCESS anyway, and writes the damage to the registry. Even GitHub Desktop's installer shipped that bug (desktop/desktop#18176).

How do you set an environment variable in cmd?

set affects the current cmd session and the processes it launches — nothing else, and nothing after the window closes:

:: Session-only — gone when this window closes
set API_KEY=abc123

:: Read it back
echo %API_KEY%

:: List everything (or filter by prefix)
set
set API

:: Inline-for-one-command needs two statements in cmd:
set DEBUG=1&& node app.js

Two traps. First, spaces are literal: set FOO = bar defines a variable named FOO  (trailing space) with value  bar — write set FOO=bar with no spaces around =; the same rule is why the chained command above has no space before && — set DEBUG=1 && would set DEBUG to 1  with a trailing space. Second, the Unix prefix form FOO=bar command does not exist in cmd at all; it produces the infamous "is not recognized" error that the NODE_NO_WARNINGS troubleshooting guide dissects.

What does setx do — and when does it bite?

setx writes the value to the registry so future processes inherit it. User scope by default; /M targets the machine scope and needs an elevated prompt:

:: Persist for the current user (takes effect in NEW terminals only)
setx API_KEY "abc123"

:: Persist machine-wide — requires "Run as administrator"
setx /M JAVA_HOME "C:\Program Files\Eclipse Adoptium\jdk-21"

:: Note: setx does NOT update the current session.
:: %API_KEY% is still undefined in this window.

How do you set environment variables in PowerShell?

PowerShell separates the two jobs cleanly: $env: for the session, the [Environment] .NET class for persistence:

# Session-only
$env:API_KEY = 'abc123'

# Inline for one command
$env:DEBUG = '1'; node app.js

# Persist for the current user — no length truncation, no admin needed
[Environment]::SetEnvironmentVariable('API_KEY', 'abc123', 'User')

# Persist machine-wide (elevated prompt required)
[Environment]::SetEnvironmentVariable('JAVA_HOME', 'C:\jdk-21', 'Machine')

# Read a specific scope (the $env: drive only shows the merged process view)
[Environment]::GetEnvironmentVariable('API_KEY', 'User')

# Delete from a scope
[Environment]::SetEnvironmentVariable('API_KEY', $null, 'User')

SetEnvironmentVariable with a scope writes the same registry keys the GUI does and broadcasts the WM_SETTINGCHANGE message — but without setx's truncation. It is the only scriptable method worth using for PATH. Note that persisting a variable does not set it in your current session; do both if you need it immediately.

What is the difference between user and system scope?

Persistent variables live in two registry locations:

When the same name exists in both, the user value wins — except PATH, which is special-cased: Windows concatenates system PATH first, then user PATH. Default to user scope; reserve system scope for variables a service or another account genuinely needs, because every system change also forces an elevation prompt and affects users you may not be thinking about.

How do you edit PATH safely?

The GUI editor is the safest tool Windows ships for this — it shows one entry per row, has no length cliff, and separates user from system cleanly. Open it directly:

# Straight to "Environment Variables" (user + system)
rundll32.exe sysdm.cpl,EditEnvironmentVariables

# Or: Win key -> type "environment" ->
# "Edit environment variables for your account" (no admin)
# "Edit the system environment variables"      (admin)

For scripts, the read-modify-write pattern against a single scope:

# Append to USER PATH without touching the system half
$userPath = [Environment]::GetEnvironmentVariable('Path', 'User')
if ($userPath -notlike '*C:\tools\bin*') {
  [Environment]::SetEnvironmentVariable('Path', "$userPath;C:\tools\bin", 'User')
}

The idempotency check matters: installers that blindly append on every run are why PATHs balloon toward the limit that makes setx destructive in the first place.

Why doesn't my new variable show up in the terminal?

Every Windows process receives a copy of its parent's environment block at creation — there is no live link to the registry. After a persistent change, Explorer is told via the WM_SETTINGCHANGE broadcast, so programs launched from the Start menu pick up the new value. Anything already running keeps its stale copy. The practical consequences:

• Windows Terminal tabs are not enough. New tabs are children of the same WindowsTerminal.exe process and inherit its old block — quit the whole app and relaunch.
• VS Code's integrated terminal inherits from VS Code. Restart VS Code itself (a full window reload), not just the terminal panel.
• Services and Docker Desktop read machine scope at their own start — restart the service, not the console. The same start-time snapshot rule shapes how Docker on Windows containers see host variables.
• No reboot is required for normal use — relaunching the process chain is sufficient. Reboot only when something at session level (e.g. the shell that launches everything) refuses to refresh.

Which method should you use?

For project configuration — API keys, database URLs, per-repo settings — persistent machine variables are the wrong layer entirely. A .env file loaded by your runtime keeps config scoped to the project and out of the registry; see the Node.js env variables guide and the .env file guide for that pattern.

When should you not use persistent environment variables?

• Secrets — registry values are plaintext, readable by any process in scope, and captured by backup tools. Use Windows Credential Manager, a secrets manager, or per-project .env files that never leave the repo directory.
• Per-project config — a global DATABASE_URL guarantees the wrong project reads it eventually. Scope config to the project with .env files or direnv-style tooling.
• Anything a script sets repeatedly — unconditional appends and rewrites are how PATH rot happens. Persistent writes belong in installers and one-time setup, guarded by an existence check.

Frequently Asked Questions

References

• Microsoft Learn — setx — official syntax, /M flag, and the documented 1,024-character limit
• Microsoft Learn — set (cmd) — session-scoped variables in the cmd shell
• .NET API — Environment.SetEnvironmentVariable — the scope semantics PowerShell uses
• desktop/desktop#18176 — GitHub Desktop's installer truncating user PATHs via setx
• Microsoft Learn — Environment Variables (Win32) — process environment blocks and WM_SETTINGCHANGE propagation