How to fix error: unable to create symlink: symbolic link privilege not held in Git

GitINTERMEDIATEMEDIUMUpdated Dec 6, 2025· 357 views

This Git error occurs on Windows when checking out a repository that contains symbolic links, but your user account lacks the privilege to create symlinks. Windows requires either administrator rights or Developer Mode enabled to create symbolic links.

Quick fix

Fixes error: unable to create symlink: symbolic link privilege not held

git clone <repository-url>
# or if already cloned:
git checkout -- .
  1. Enable Developer Mode on Windows 10/11
  2. Run Git as Administrator
  3. Grant symlink privilege via Local Security Policy
  4. Configure Git to not use symlinks (workaround)
git — error
git clone <repository-url>
# or if already cloned:
git checkout -- .
error: unable to create symlink: symbolic link privilege not held

What this error means

When Git attempts to check out files from a repository, it tries to recreate the exact file structure stored in the repository, including symbolic links (symlinks). On Unix-like systems, symlinks are common and easily created by any user. However, Windows has historically restricted symlink creation as a security measure. This error occurs because: 1. The repository you're cloning or checking out contains symbolic links 2. Your Windows user account doesn't have the "Create symbolic links" privilege 3. Git is configured to use native symlinks (`core.symlinks = true`) but cannot create them By default, Windows restricts symlink creation to administrators. This is a security feature because symlinks could potentially be used to trick programs into accessing files they shouldn't. Starting with Windows 10 (build 14972), Microsoft added Developer Mode which grants this privilege to non-admin accounts. When Git encounters this situation, it will either fail the checkout or fall back to creating text files containing the symlink target path instead of actual symlinks, depending on your Git configuration.

Typical symptoms

  • Error 'unable to create symlink' when cloning or checking out a repository
  • Error 'symbolic link privilege not held' during git checkout
  • Git clone completes but some files are broken or contain unexpected text paths
  • Build or application errors due to missing symlinked files after clone
  • Error only appears on Windows, not on Linux or macOS
  • Repository works fine when cloned with administrator privileges
  • Files that should be symlinks contain plain text with a path instead

Common causes

  1. Windows user account lacks 'Create symbolic links' privilege (most common)
  2. Developer Mode not enabled on Windows 10/11
  3. Git for Windows not installed with symlink support option
  4. Running Git Bash or terminal without administrator privileges
  5. Group Policy restricts symlink creation in corporate environments
  6. Repository contains Unix-style symlinks being checked out on Windows
  7. core.symlinks Git setting is true but system cannot create symlinks

How to fix "error: unable to create symlink: symbolic link privilege not held"

1Enable Developer Mode on Windows 10/11

The easiest solution for personal computers is to enable Developer Mode, which grants symlink privileges to your user account:

1. Press Windows + I to open Settings
2. Go to Privacy & security > For developers (Windows 11) or Update & Security > For Developers (Windows 10)
3. Toggle Developer Mode to On
4. Accept the confirmation dialog
5. Restart your computer (recommended)

After enabling Developer Mode, try your Git operation again:

bash
git clone <repository-url>
# or if already cloned:
git checkout -- .
2Run Git as Administrator

If you cannot enable Developer Mode, run your Git client with administrator privileges:

For Git Bash:
1. Right-click on "Git Bash" in the Start menu
2. Select "Run as administrator"
3. Navigate to your repository and run your Git commands

For Command Prompt or PowerShell:
1. Search for "cmd" or "PowerShell" in the Start menu
2. Right-click and select "Run as administrator"
3. Run your Git commands

For VS Code integrated terminal:
1. Close VS Code
2. Right-click on VS Code and select "Run as administrator"
3. Open your project and use the integrated terminal

bash
# Now clone or checkout with admin privileges
git clone <repository-url>

Note: Running as administrator is not ideal for everyday development as it can cause file permission issues.

3Grant symlink privilege via Local Security Policy

For a permanent solution without Developer Mode (requires Windows Pro/Enterprise):

1. Press Windows + R, type secpol.msc, and press Enter
2. Navigate to Local Policies > User Rights Assignment
3. Find Create symbolic links and double-click it
4. Click Add User or Group
5. Enter your username or a group you belong to
6. Click OK and close the policy editor
7. Log out and log back in (or restart)

Verify the privilege was granted:

powershell
whoami /priv | findstr SeCreateSymbolicLinkPrivilege

You should see SeCreateSymbolicLinkPrivilege listed.

4Configure Git to not use symlinks (workaround)

If you cannot get symlink privileges, configure Git to use text files instead of actual symlinks:

bash
# Disable symlinks for a specific repository
git config core.symlinks false

# Or disable globally
git config --global core.symlinks false

Then reset your working directory:

bash
git checkout -- .
# or reclone the repository

Warning: With core.symlinks false, Git creates plain text files containing the symlink target path. This may break builds or applications that rely on actual symlinks. Use this only if symlinks aren't critical to your project.

To check what files are symlinks in the repo:

bash
git ls-files -s | grep "^120000"
5Reinstall Git for Windows with symlink support

When installing Git for Windows, ensure symlink support is enabled:

1. Download the latest [Git for Windows](https://git-scm.com/download/win)
2. Run the installer
3. During installation, on the "Configuring extra options" screen, check Enable symbolic links
4. Complete the installation

If Git is already installed, you can modify the installation:
1. Go to Settings > Apps > Git
2. Click Modify or run the installer again
3. Ensure the symlink option is checked

After reinstalling, verify symlinks are enabled:

bash
git config --system core.symlinks

This should return true.

6Use WSL (Windows Subsystem for Linux) instead

For projects that heavily use symlinks, consider using WSL where symlinks work natively:

1. Enable WSL if not already:

powershell
wsl --install

2. Install a Linux distribution from the Microsoft Store (e.g., Ubuntu)

3. Clone and work with the repository inside WSL:

bash
# In WSL terminal
cd ~
git clone <repository-url>

WSL handles symlinks like a native Linux environment, avoiding Windows symlink limitations entirely.

You can access WSL files from Windows at \\wsl$\Ubuntu\home\<username> or use VS Code's Remote - WSL extension for seamless editing.

Advanced notes

### Understanding Windows Symlink Types

Windows actually supports multiple types of links:

1. Symbolic Links (symlinks) - Requires special privilege, works like Unix symlinks
2. Junction Points - Only for directories, doesn't require special privilege
3. Hard Links - Only for files on the same volume, doesn't require special privilege

Git on Windows uses actual symbolic links when core.symlinks = true. Some tools work around this by using junctions for directory symlinks, but Git doesn't do this automatically.

### Corporate/Domain Environments

In enterprise environments, Group Policy often restricts symlink creation. Even Developer Mode might not work if GPO overrides it. Contact your IT department to request the SeCreateSymbolicLinkPrivilege for your account.

Check if Group Policy is blocking you:

powershell
gpresult /h gpreport.html
# Open gpreport.html and search for "symbolic link"

### Git Configuration Hierarchy

The core.symlinks setting can be set at multiple levels:

bash
# Check all levels
git config --system core.symlinks  # System-wide
git config --global core.symlinks  # User-wide
git config --local core.symlinks   # Repository-specific

The Git for Windows installer sets this at the system level. You can override at lower levels.

### Checking Repository Symlinks

Before cloning, you can check if a repository uses symlinks:

bash
# List all symlinks in the repository
git ls-tree -r HEAD | grep "^120000"

The mode 120000 indicates a symbolic link in Git.

### NTFS vs FAT32

Symlinks only work on NTFS file systems. If your repository is on a FAT32 or exFAT drive (like some USB drives), symlinks won't work regardless of privileges.

### CI/CD Considerations

When running Git on Windows CI/CD agents (Azure DevOps, GitHub Actions Windows runners), ensure the agent has symlink privileges:

yaml
# GitHub Actions - use windows-latest which has symlink support
runs-on: windows-latest
steps:
  - uses: actions/checkout@v4
# Symlinks should work if the repo has them

For self-hosted Windows agents, configure the agent user with symlink privileges.

Frequently asked questions

What does "error: unable to create symlink: symbolic link privilege not held" mean?
When Git attempts to check out files from a repository, it tries to recreate the exact file structure stored in the repository, including symbolic links (symlinks). On Unix-like systems, symlinks are common and easily created by any user. However, Windows has historically restricted symlink creation as a security measure.
How do I fix "error: unable to create symlink: symbolic link privilege not held"?
This Git error occurs on Windows when checking out a repository that contains symbolic links, but your user account lacks the privilege to create symlinks. Windows requires either administrator rights or Developer Mode enabled to create symbolic links.
What causes "error: unable to create symlink: symbolic link privilege not held"?
Windows user account lacks 'Create symbolic links' privilege (most common) Developer Mode not enabled on Windows 10/11 Git for Windows not installed with symlink support option
Is the "error: unable to create symlink: symbolic link privilege not held" error serious?
It is a medium-severity error — more of a blocker than a risk. The steps above resolve it.

Official resources & further reading