Skip to main content

How to Set a Global Environment Variable Persistently (SETX) in Batch Script

The standard SET command in a batch script is temporary. It creates or modifies a variable that exists only for the duration of that specific command prompt session. When the window is closed, the variable is gone. For changes that need to persist—surviving reboots and being available in all future command prompts—you must use a different, more powerful tool: SETX.

This guide will teach you how to use the SETX command to create permanent user and system-level environment variables. You will learn the critical difference between SET and SETX, including the most common "gotcha" that confuses new users, and see a practical example for permanently adding a tool to your system's PATH.

The Core Command: SETX​

The SETX command is a command-line tool that writes variables to the Windows Registry. This is what makes its changes permanent. It can create variables at two different levels: the current user's environment or the system-wide environment.

The basic syntax is: SETX VariableName "Value"

Setting a User Variable vs. a System Variable (/M)​

By default, SETX creates a user environment variable. This means the variable will only be available to the user who ran the command.

Example: Setting a User Variable

@ECHO OFF
ECHO Setting a persistent variable for the current user...
SETX MY_APP_VERSION "1.2.3"

After running this, you can open a new command prompt, type ECHO %MY_APP_VERSION%, and it will display 1.2.3.

To create a system environment variable (also called a machine-level variable), which is available to all users on the computer, you must use the /M switch. This action requires administrator privileges.

Example: Setting a System Variable

@ECHO OFF
REM This part of the script MUST be run as an Administrator.
ECHO Setting a persistent, system-wide variable...
SETX /M JAVA_HOME "C:\Program Files\Java\jdk-11"

CRITICAL DISTINCTION: SET vs. SETX​

Understanding the difference between these two commands is essential to using them correctly.

FeatureSETSETX
ScopeCurrent command session onlyFuture command sessions
PersistenceVolatile. Gone when cmd closes.Permanent. Written to the Registry.
ImmediacyImmediate. Available right away.Delayed. Does not affect the current session.
Admin RightsNot required.Required for system (/M) variables.
note

The most important point is immediacy. When you run SETX, the variable is written to the registry for future sessions, but it is NOT loaded into your current command prompt environment. This is the source of most confusion.

How to Read the New Variable in the Same Script​

Because SETX doesn't affect the current session, how do you set a variable and use it immediately? The standard pattern is to run both SETX and SET.

The "Set and Use" Pattern​

@ECHO OFF
SET "NewVarValue=MyImportantData"

ECHO Setting the variable for future sessions...
SETX MyPersistentVar "%NewVarValue%"

ECHO Setting the variable for the CURRENT session...
SET MyPersistentVar="%NewVarValue%"

ECHO.
ECHO The variable is now available immediately:
ECHO %MyPersistentVar%
note

This pattern gives you the best of both worlds: the variable is saved permanently for the future, and it's loaded into the current session so your script can continue to use it.

Common Pitfalls and How to Solve Them​

Problem: SETX Does Not Affect the Current Session​

As explained above, this is the main pitfall. A user runs SETX MyVar "Hello" and then ECHO %MyVar% and is confused when it's empty.

Solution: Use the "Set and Use" pattern from , or simply open a new command prompt to see the new variable.

Problem: The Script is Not Run as Administrator​

If you try to set a system-level variable (/M) from a standard command prompt, it will fail.

Example of script with error:

ERROR: Access to the registry path is denied.

Solution: The script must be run from an elevated command prompt. Right-click cmd.exe or your batch file and select "Run as administrator."

Problem: How to Delete a Variable with SETX​

SETX has no /DELETE switch. You cannot use it to directly remove a variable from the registry.

Solution: The standard workaround is to set the variable's value to an empty string. This doesn't remove the key from the registry, but it makes the variable expand to nothing, which is usually sufficient.

REM This effectively "deletes" the variable for future sessions.
SETX MyUnusedVar ""

Practical Example: Permanently Adding a Folder to the PATH​

This is the most common use case for SETX. This script permanently adds a custom tools folder to the system's PATH, making its executables available from any command prompt.

@ECHO OFF
SETLOCAL
REM This script MUST be run as an Administrator.

SET "TOOL_PATH=C:\MyCustomTools"
ECHO --- Adding a new folder to the system PATH ---
ECHO.
ECHO Folder to add: "%TOOL_PATH%"
ECHO.

REM IMPORTANT: We must read the existing PATH and append our new path to it.
REM The /M switch makes this a system-wide change.
SETX /M PATH "%PATH%;%TOOL_PATH%"

ECHO.
ECHO [SUCCESS] "%TOOL_PATH%" has been added to the system PATH.
ECHO Please open a NEW command prompt to see the changes.
ENDLOCAL

Conclusion​

SETX is the correct and only built-in command-line tool for making permanent changes to the environment variables from a batch script.

Key takeaways for using SETX effectively:

  • SET is for temporary, session-only variables. SETX is for permanent, future variables.
  • SETX does not affect the current session. Use SET immediately after if you need the variable right away.
  • Use the /M switch to create system-wide variables, which requires administrator rights.
  • Use SETX VarName "" to effectively "delete" a persistent variable.

By understanding the unique behavior of SETX, you can write powerful setup and configuration scripts that reliably modify the Windows environment.

Table of Contents