Skip to main content

How to Run a Script from a UNC Path in Batch Script

In a networked environment, it's common to store scripts and tools on a central file server, accessible via a UNC (Universal Naming Convention) path like \\Server\Share. While you can easily execute a script from a UNC path, a significant and often surprising limitation of the cmd.exe environment is that the current working directory does not change to that network location. This can cause the script to fail if it expects to find other files relative to its own location.

This guide will explain this core problem and teach you the standard and most effective solution: using the PUSHD and POPD commands to reliably map a temporary drive letter to the UNC path, allowing your script to run with the correct and expected working directory.

The Core Problem: CD Does Not Work with UNC Paths​

The CD (Change Directory) command, which is the standard way to change the working directory, cannot navigate to a UNC path.

An exmaple of script with error. If you open a command prompt and type:

C:\> CD \\FileServer\Scripts

You will get an error:

CMD does not support UNC paths as current directories.

This means if your script (\\FileServer\Scripts\MyScript.bat) contains a line like COPY config.ini C:\Temp\, it will fail because the command processor is still in the original directory (C:\) and cannot find config.ini on the network share.

The Solution: PUSHD to Temporarily Map a Drive​

The PUSHD command is the definitive solution to this problem. It is an enhanced version of CD that has two key functions:

  1. It "pushes" your current directory onto a memory stack so you can easily return to it later.
  2. Crucially, if you give it a UNC path, it will automatically create a temporary network drive mapping to that path and then change to it.

Syntax: PUSHD "\\Server\Share\Path"

Windows will automatically map the UNC path to the next available drive letter, starting from Z: and working backwards.

Basic Example: Running a Script from a Network Share​

Let's create a simple script that correctly sets its working directory when run from a network share.

\FileServer\Scripts\Test.bat
@ECHO OFF
ECHO --- My Network Script ---
ECHO.
ECHO Initial working directory: %CD%
ECHO.
PAUSE

REM --- This is the crucial command ---
ECHO Setting the current directory to the script's own UNC path...
PUSHD "%~dp0"

ECHO.
ECHO New working directory: %CD%
ECHO Notice the new temporary drive letter!
ECHO.
PAUSE

ECHO --- Script can now find its own resources ---
ECHO For example, trying to read a file in the same folder:
TYPE "%~dp0\test_data.txt"

REM --- Clean up the temporary drive mapping ---
POPD

ECHO.
ECHO After POPD, the directory is restored: %CD%
PAUSE
note
  • %~dp0: This special variable always expands to the drive and path of the running script. When the script is on a share, this will be the UNC path.

How PUSHD and POPD Work​

  • PUSHD "\\Server\Share": The command processor sees the UNC path. It finds the next free drive letter (e.g., Z:), maps Z: to \\Server\Share, and then changes the current directory to Z:\.
  • POPD: This command "pops" the last directory off the stack. If that directory was a temporary drive mapping created by PUSHD, it unmaps the drive letter and returns you to your original directory.

PUSHD and POPD are designed to be used as a pair to ensure that your script is "well-behaved" and cleans up after itself.

Common Pitfalls and How to Solve Them​

  • Forgetting to Use PUSHD: The most common mistake is to write a script on a network share that assumes its current directory is the share path. This script will always fail when run from a local drive. Solution: The very first command in any script designed to run from a UNC path should be PUSHD "%~dp0".

  • Permissions: The user running the script must have the necessary network permissions to access the UNC share. If they can't browse to it in File Explorer, PUSHD will also fail.

  • Forgetting POPD: If you forget to call POPD at the end of your script, the temporary drive mapping will remain until the cmd.exe session is closed. Solution: It's a best practice to always pair a PUSHD with a POPD before your script exits.

Practical Example: A Robust "Wrapper" Script​

This is a very common and powerful pattern. You have a "launcher" script on a local machine that needs to run a main script located on a network share.

For example, the Local Launcher Script:

C:\Launch.bat
@ECHO OFF
TITLE Main Launcher

ECHO --- Launching Main Script from Network ---
ECHO This script will now run the main process from the central server.
ECHO.

REM --- Use PUSHD to navigate to the network and run the script ---
PUSHD "\\FileServer\MainApp"

IF %ERRORLEVEL% NEQ 0 (
    ECHO [ERROR] Could not connect to the network share.
    PAUSE
    GOTO :EOF
)

ECHO Now running the main script from: %CD%
CALL MainScript.bat

REM --- POPD cleans up and returns us to our original directory ---
POPD

ECHO --- Main script has finished. Returned to local context. ---
ECHO Current directory: %CD%
PAUSE
note

This pattern ensures that MainScript.bat runs with \\FileServer\MainApp as its working directory, allowing it to find all its necessary files.

Conclusion​

The PUSHD and POPD commands are the essential and definitive tools for reliably working with scripts located on UNC paths.

Key takeaways for success:

  • The standard CD command cannot be used with UNC paths.
  • PUSHD "\\Server\Share" is the solution. It automatically creates a temporary drive mapping and changes to it.
  • The best practice for any script that lives on a network share is to begin with the command PUSHD "%~dp0". This makes the script's own location its working directory.
  • Always pair a PUSHD with a POPD at the end of your script to unmap the temporary drive and return to the original directory.

Table of Contents