Skip to main content

How to Replace a Substring with Another String in Batch Script

One of the most essential text manipulation tasks is finding all occurrences of a specific piece of text within a larger string and replacing them with a new value. This is crucial for updating placeholders in template files, correcting common errors in data, or changing filenames in bulk. Windows Batch provides a simple, fast, and powerful "pure-batch" method for this using its native string substitution syntax.

This guide will teach you how to use this built-in substitution feature to replace substrings. We will also cover the more flexible and modern approach using a PowerShell one-liner, which is a great alternative for more complex needs like case-insensitive replacements.

The Core Method (Pure Batch): String Substitution​

This is the standard, most efficient, and "batch-native" way to perform a replacement. The syntax is built directly into the SET command.

Syntax: SET "MyVar=%MyVar:find=replace%"

  • MyVar: The name of the variable you are operating on.
  • :find=replace: The operation.
    • :: The separator that begins the substitution.
    • find: The substring you are searching for.
    • =: The assignment operator.
    • replace: The new string that will replace every occurrence of find.

When used inside a FOR loop or IF block, you must use Delayed Expansion: SET "MyVar=!MyVar:find=replace!"

For more advanced needs, especially case-insensitive replacements, a PowerShell one-liner is the superior tool.

Syntax: powershell -Command "'Your String Here'.Replace('find', 'replace')"

PowerShell's .Replace() method is highly flexible and easy to read, making it a powerful addition to your batch scripting toolkit.

Basic Example: Replacing a Word in a String​

Let's replace all instances of the word "staging" with "production" in a connection string.

Method 1: Pure Batch Script​

@ECHO OFF
SETLOCAL ENABLEDELAYEDEXPANSION

SET "ConnectionString=Server=db-staging-01;User=app_user;Env=staging"
ECHO Original: !ConnectionString!

SET "UpdatedString=!ConnectionString:staging=production!"

ECHO Batch Method Result: !UpdatedString!
ENDLOCAL

Output:

Original: Server=db-staging-01;User=app_user;Env=staging
Batch Method Result: Server=db-production-01;User=app_user;Env=production

Method 2: PowerShell Script​

@ECHO OFF
SET "ConnectionString=Server=db-staging-01;User=app_user;Env=staging"
ECHO Original: !ConnectionString!
SET "UpdatedString="

FOR /F "delims=" %%V IN (
    'powershell -Command "'%ConnectionString%'.Replace('staging', 'production')"'
) DO (
    SET "UpdatedString=%%V"
)

ECHO PowerShell Method Result: %UpdatedString%

Output:

Original: Server=db-staging-01;User=app_user;Env=staging
PowerShell Method Result: Server=db-production-01;User=app_user;Env=production
note

Notice that the batch method correctly replaced both occurrences of "staging".

How the Batch Substitution Works​

The syntax !MyVar:find=replace! is a special expansion that the cmd.exe interpreter handles directly. When the line is executed, the interpreter finds the variable MyVar, scans its content for all occurrences of the find string, and substitutes them with the replace string before assigning the final result back to the variable. This is an all-at-once, global replacement.

Common Pitfalls and How to Solve Them​

Problem: The Replacement is Case-Sensitive​

This is the most significant limitation of the pure-batch method. The substitution is always case-sensitive. It will not replace "Staging" if your find string is "staging".

Solution: Use PowerShell. Its .Replace() method is also case-sensitive, but PowerShell's -replace operator is case-insensitive by default, making it the perfect tool for this.

The following script is Case-Insensitive Replacement with PowerShell:

@ECHO OFF
SET "MyString=This is a Test String."
SET "Find=test"
SET "Replace=DEMO"
SET "Result="

FOR /F "delims=" %%V IN (
    'powershell -Command "'%MyString%' -replace '%Find%', '%Replace%'"'
) DO (
    SET "Result=%%V"
)

ECHO Result: %Result%

Output:

Result: This is a DEMO String.

Problem: Delayed Expansion is Not Enabled​

This is a very common mistake. If you are performing a replacement inside a FOR loop or IF block, you must use delayed expansion (!). Using standard percent expansion (%) will fail because the variable is expanded only once when the block is parsed, not during execution.

Solution: Always Use SETLOCAL ENABLEDELAYEDEXPANSION​

Enable delayed expansion at the start of your script or subroutine, and use the !MyVar:find=replace! syntax for all string replacements inside loops and code blocks.

Practical Example: Updating a Version Number in a File​

This script demonstrates a real-world use case. It reads a configuration file line by line, finds a specific line containing a version placeholder, replaces it with a new version number, and writes the result to a new file.

Consider this configuration file:

AppName=MyCoolApp
Version=__VERSION__
Author=Admin

and the script:

@ECHO OFF
SETLOCAL ENABLEDELAYEDEXPANSION

SET "NEW_VERSION=1.2.3"
SET "TEMPLATE_FILE=template.conf"
SET "OUTPUT_FILE=production.conf"

ECHO Updating version placeholder in "%TEMPLATE_FILE%"...

(FOR /F "delims=" %%L IN (%TEMPLATE_FILE%) DO (
    SET "line=%%L"
    REM Perform the replacement on each line
    SET "line=!line:__VERSION__=%NEW_VERSION%!"
    ECHO !line!
)) > "%OUTPUT_FILE%"

ECHO.
ECHO [SUCCESS] New config file created: "%OUTPUT_FILE%"
TYPE "%OUTPUT_FILE%"
ENDLOCAL

Conclusion​

String replacement is a powerful and easy-to-use feature in Windows Batch, making it simple to manipulate text for a wide variety of tasks.

  • The pure-batch substitution method (!VAR:find=replace!) is extremely fast and effective for all case-sensitive replacements.
  • The PowerShell -replace operator is the recommended best practice for case-insensitive needs. It is more powerful and provides the flexibility that the native batch syntax lacks.

By choosing the right tool for your specific needs, you can handle any string replacement task with confidence.

Table of Contents