How to fix fatal: 'worktree' is locked in Git

GitBEGINNERLOWUpdated Dec 6, 2025· 185 views

This error occurs when Git prevents operations on a worktree because it has been explicitly locked. Unlock the worktree using 'git worktree unlock' or use --force flags for remove/move operations.

Quick fix

Fixes fatal: 'worktree' is locked

# List all worktrees with verbose output
git worktree list --verbose
  1. List worktrees and check lock status
  2. Unlock the worktree
  3. Force remove a locked worktree
  4. Force move a locked worktree
git — error
# List all worktrees with verbose output
git worktree list --verbose
fatal: 'worktree' is locked

What this error means

The "fatal: 'worktree' is locked" error indicates that Git is preventing you from performing certain operations (like removing, moving, or pruning) on a linked worktree because it has been locked. Worktree locking is a deliberate safety mechanism in Git to protect working trees that might be stored on removable media or network shares that aren't always mounted. When a worktree is locked, Git refuses to: - Remove the worktree with `git worktree remove` - Move the worktree with `git worktree move` - Automatically prune the worktree's administrative files - Add a new worktree at the same path This protection exists because if Git pruned or removed a worktree while the storage was temporarily unavailable, you could lose work or end up with a corrupted repository state when the storage comes back online. The lock is stored as a file in the main repository's `.git/worktrees/<name>/locked` file. This file may optionally contain a reason string explaining why the worktree was locked, which can be helpful when deciding whether it's safe to unlock.

Typical symptoms

  • git worktree remove fails with 'fatal: '<path>' is locked'
  • git worktree move refuses to relocate the worktree
  • git worktree prune does not clean up a stale worktree
  • git worktree list shows '(locked)' next to the worktree entry
  • Unable to add a new worktree at a path that was previously used

Common causes

  1. Worktree was explicitly locked with 'git worktree lock' command
  2. Worktree is on a removable drive or network share and was locked to prevent accidental pruning
  3. Previous operation locked the worktree and the lock was never removed
  4. Another process or script locked the worktree for exclusive access
  5. Lock file exists due to an interrupted or crashed Git operation
  6. Worktree was locked by a CI/CD system or automated backup process

How to fix "fatal: 'worktree' is locked"

1List worktrees and check lock status

First, identify which worktrees are locked and examine their status:

bash
# List all worktrees with verbose output
git worktree list --verbose

The output will show each worktree with its status. Locked worktrees will display "(locked)" after their path:

bash
/home/user/project           abc1234 [main]
/home/user/project-feature   def5678 [feature] (locked)

The verbose flag also displays the lock reason if one was provided when locking.

2Unlock the worktree

If you want to allow operations on the worktree, unlock it with:

bash
# Unlock by worktree path
git worktree unlock /path/to/worktree

# Or unlock by the worktree directory name relative to main repo
git worktree unlock ../project-feature

After unlocking, you can perform remove, move, or prune operations on the worktree.

bash
# Verify the worktree is now unlocked
git worktree list
3Force remove a locked worktree

If you want to remove a locked worktree without unlocking it first, use the --force flag twice:

bash
# Force remove a locked worktree
git worktree remove --force --force /path/to/worktree

# Or using shorthand
git worktree remove -f -f /path/to/worktree

Warning: Using double --force bypasses both the lock check and any uncommitted changes check. Make sure you've saved any important work before using this option.

4Force move a locked worktree

To move a locked worktree to a new location without unlocking, use double --force:

bash
# Force move a locked worktree
git worktree move --force --force /old/path /new/path

# Or using shorthand
git worktree move -f -f /old/path /new/path

This is useful when you need to relocate a worktree from a failing drive or unmounted network share.

5Add a worktree at a locked path

If you're trying to create a new worktree at a path that's still registered as locked (perhaps from a deleted worktree), use double --force:

bash
# Force add worktree at a path that's locked
git worktree add --force --force /path/to/worktree feature-branch

Before doing this, make sure the original worktree at that path is truly gone and not just temporarily unavailable.

6Manually remove the lock file

If the standard unlock command doesn't work, you can manually remove the lock file from the main repository:

bash
# Navigate to your main repository
cd /path/to/main/repo

# List the worktrees directory
ls -la .git/worktrees/

# Find and remove the lock file for the specific worktree
rm .git/worktrees/<worktree-name>/locked

Replace <worktree-name> with the directory name of your worktree (usually the final component of the worktree path).

bash
# Example: if worktree was at /home/user/project-feature
rm .git/worktrees/project-feature/locked

After removing the lock file, run git worktree list to verify the worktree is no longer locked.

7Prune stale worktree entries

If you've manually deleted a worktree directory but Git still tracks it, prune the stale entries:

bash
# Dry run to see what would be pruned
git worktree prune --dry-run

# Actually prune stale worktree administrative files
git worktree prune

Note: git worktree prune will NOT remove locked worktrees, even if their directories are missing. You must unlock or force-remove them first.

bash
# To see verbose output during prune
git worktree prune --verbose
8Understand why the worktree was locked

Before unlocking, check if there was a reason provided for the lock:

bash
# Check the lock file content directly
cat .git/worktrees/<worktree-name>/locked

If the file exists but is empty, no reason was given. If it contains text, that's the reason the worktree was locked (e.g., "On network share - do not prune").

When to keep a worktree locked:
- It's on a USB drive or external storage that's sometimes disconnected
- It's on a network share that may be temporarily unavailable
- You want to prevent accidental deletion during cleanup operations

Lock a worktree with a reason:

bash
git worktree lock --reason "On external backup drive" /path/to/worktree

Advanced notes

How worktree locking works internally:

Git stores worktree metadata in .git/worktrees/<name>/ within your main repository. When you lock a worktree with git worktree lock, Git creates a file called locked in that directory. The file's contents are the lock reason (if provided) or empty.

Automating worktree management in scripts:

When writing scripts that manage worktrees, handle locks gracefully:

bash
#!/bin/bash
WORKTREE_PATH="/path/to/worktree"

# Check if worktree is locked before attempting removal
if git worktree list | grep -q "$WORKTREE_PATH.*locked"; then
    echo "Worktree is locked, unlocking..."
    git worktree unlock "$WORKTREE_PATH"
fi

git worktree remove "$WORKTREE_PATH"

Worktree corruption recovery:

If your main repository's .git/worktrees directory becomes corrupted:

1. Back up the main repository
2. List the contents: ls -la .git/worktrees/
3. For each stale entry, check if the worktree directory still exists
4. Remove stale administrative directories: rm -rf .git/worktrees/<stale-name>
5. Re-register valid worktrees: git worktree add <path> <branch>

Git LFS and worktrees:

Some Git LFS post-checkout hooks can interfere with worktree operations. If you encounter lock-related issues with Git LFS, check GitHub issue git-lfs/git-lfs#2848 for workarounds.

Best practices for worktree locks:

- Always provide a --reason when locking worktrees so future-you knows why
- Document locked worktrees in your project's README or contributing guide
- Periodically audit locked worktrees: git worktree list | grep locked
- In CI/CD, avoid locking worktrees unless absolutely necessary

Frequently asked questions

What does "fatal: 'worktree' is locked" mean?
The "fatal: 'worktree' is locked" error indicates that Git is preventing you from performing certain operations (like removing, moving, or pruning) on a linked worktree because it has been locked. Worktree locking is a deliberate safety mechanism in Git to protect working trees that might be stored on removable media or network shares that aren't always mounted. When a worktree is locked, Git refuses to: - Remove the worktree with git worktree remove - Move the worktree with git worktree move - Automatically prune the worktree's administrative files - Add a new worktree at the same path This protection exists because if Git pruned or removed a worktree while the storage was temporarily unavailable, you could lose work or end up with a corrupted repository state when the storage comes back online.
How do I fix "fatal: 'worktree' is locked"?
This error occurs when Git prevents operations on a worktree because it has been explicitly locked. Unlock the worktree using 'git worktree unlock' or use --force flags for remove/move operations.
What causes "fatal: 'worktree' is locked"?
Worktree was explicitly locked with 'git worktree lock' command Worktree is on a removable drive or network share and was locked to prevent accidental pruning Previous operation locked the worktree and the lock was never removed
Is the "fatal: 'worktree' is locked" error serious?
It is a low-severity error — more of a blocker than a risk. The steps above resolve it.

Official resources & further reading