How to fix fatal: unknown option --no-optional-locks (git version too old) in Git

GitBEGINNERLOWUpdated Dec 6, 2025· 253 views

The 'fatal: unknown option --no-optional-locks' error occurs when a tool or script invokes Git with the --no-optional-locks flag, but the installed Git version is too old to support this option. This typically happens in CI/CD pipelines, IDEs, or build systems that expect a newer Git version.

Quick fix

Fixes fatal: unknown option --no-optional-locks (git version too old)

# Check Git version
git --version

# Expected output for a version that supports --no-optional-locks:
# git version 2.15.0 or higher
  1. Check your current Git version
  2. Update Git on Ubuntu/Debian
  3. Update Git on CentOS/RHEL/Amazon Linux
  4. Update Git on macOS
git — error
# Check Git version
git --version
# Expected output for a version that supports --no-optional-locks:
# git version 2.15.0 or higher
fatal: unknown option --no-optional-locks (git version too old)

What this error means

The "--no-optional-locks" option was introduced in Git 2.15 (released October 2017). This flag tells Git to skip acquiring optional locks that could cause conflicts with concurrent processes or file system watchers. When you see "fatal: unknown option --no-optional-locks", it means the Git version installed on your system predates version 2.15 and doesn't recognize this flag. This error commonly appears in: - **CI/CD pipelines**: Build systems like GitHub Actions, GitLab CI, or Jenkins may use scripts or tools that pass this flag to Git - **IDE integrations**: Visual Studio Code, IntelliJ, and other editors use this flag to query Git status without interfering with concurrent Git operations - **Build tools**: Package managers, version control plugins, and automation scripts often rely on this flag for safer Git operations - **Docker containers**: Base images may include older Git versions that don't support newer flags The --no-optional-locks option is particularly useful when multiple processes access the same Git repository simultaneously, preventing lock file conflicts that could cause commands to fail or hang.

Typical symptoms

  • Error: 'fatal: unknown option --no-optional-locks'
  • Build fails in CI/CD pipeline with Git-related error
  • IDE shows Git errors when checking repository status
  • VS Code Git integration stops working or shows errors
  • Package manager commands fail when checking Git state
  • Docker build fails when running Git commands
  • Pre-commit hooks or Git hooks fail with unknown option error
  • Automation scripts that invoke Git fail unexpectedly
  • Error occurs in environments with system-installed Git
  • Works locally but fails in container or server environment

Common causes

  1. Git version is older than 2.15 (released October 2017)
  2. CI/CD runner or container uses outdated base image with old Git
  3. System package manager provides outdated Git version
  4. Multiple Git installations with incorrect PATH priority
  5. Docker image uses minimal OS with old Git package
  6. Tool or IDE passes --no-optional-locks flag to Git command
  7. Enterprise or older Linux distribution has frozen Git version
  8. macOS Command Line Tools haven't been updated
  9. Windows Git for Windows installation is outdated
  10. SSH into server with outdated system Git

How to fix "fatal: unknown option --no-optional-locks (git version too old)"

1Check your current Git version

First, verify which Git version is installed:

bash
# Check Git version
git --version

# Expected output for a version that supports --no-optional-locks:
# git version 2.15.0 or higher

If your version is below 2.15, you need to upgrade Git. You can also check when --no-optional-locks was added:

bash
# Test if the flag is supported
git --no-optional-locks status
# If this fails with "unknown option", upgrade is needed
2Update Git on Ubuntu/Debian

The default Git package in Ubuntu/Debian repositories is often outdated. Use the official Git PPA for the latest version:

bash
# Add the official Git PPA
sudo add-apt-repository ppa:git-core/ppa -y
sudo apt update

# Install or upgrade Git
sudo apt install git -y

# Verify the new version
git --version

For Debian without add-apt-repository:

bash
# Install dependencies
sudo apt install software-properties-common -y

# Add the PPA manually
echo "deb http://ppa.launchpad.net/git-core/ppa/ubuntu focal main" | sudo tee /etc/apt/sources.list.d/git-core.list
sudo apt-key adv --keyserver keyserver.ubuntu.com --recv-keys E1DD270288B4E6030699E45FA1715D88E1DF1F24
sudo apt update
sudo apt install git -y
3Update Git on CentOS/RHEL/Amazon Linux

Enterprise Linux distributions often have older Git versions. Use the IUS repository or compile from source:

bash
# For CentOS/RHEL 7+ - Use IUS repository
sudo yum install -y https://repo.ius.io/ius-release-el7.rpm
sudo yum install -y git236  # or latest available

# For Amazon Linux 2
sudo yum install -y git

# For Amazon Linux 2023
sudo dnf install -y git

# For RHEL 8/9 or CentOS Stream
sudo dnf install -y git

If repositories don't have a recent enough version, compile from source:

bash
# Install build dependencies
sudo yum groupinstall -y "Development Tools"
sudo yum install -y curl-devel expat-devel gettext-devel openssl-devel zlib-devel perl-ExtUtils-MakeMaker

# Download and compile Git
cd /tmp
curl -LO https://github.com/git/git/archive/refs/tags/v2.43.0.tar.gz
tar -xzf v2.43.0.tar.gz
cd git-2.43.0
make prefix=/usr/local all
sudo make prefix=/usr/local install

# Verify installation
/usr/local/bin/git --version
4Update Git on macOS

macOS includes Git with Xcode Command Line Tools, but it may be outdated:

bash
# Update Xcode Command Line Tools (includes Git)
xcode-select --install

# Or install/update via Homebrew (recommended)
brew install git

# Ensure Homebrew's Git takes priority
echo 'export PATH="/opt/homebrew/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

# Verify
which git  # Should show /opt/homebrew/bin/git
git --version

If using an Intel Mac:

bash
echo 'export PATH="/usr/local/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc
5Update Git on Windows

Update Git for Windows to the latest version:

powershell
# If Git is already installed, update it
git update-git-for-windows

# Or download the latest installer from:
# https://git-scm.com/download/win

Using Chocolatey:

powershell
choco upgrade git -y

Using winget:

powershell
winget upgrade Git.Git

After updating, restart your terminal or IDE to pick up the new version.

6Update Git in Docker containers

Update your Dockerfile to install a recent Git version:

Alpine Linux:

dockerfile
FROM alpine:3.19
# Alpine 3.15+ includes Git 2.34+
RUN apk add --no-cache git

Ubuntu/Debian:

dockerfile
FROM ubuntu:22.04
RUN apt-get update && apt-get install -y software-properties-common \
    && add-apt-repository ppa:git-core/ppa -y \
    && apt-get update \
    && apt-get install -y git \
    && rm -rf /var/lib/apt/lists/*

Amazon Linux 2:

dockerfile
FROM amazonlinux:2
RUN yum install -y tar gzip make gcc curl-devel expat-devel gettext-devel \
    openssl-devel zlib-devel perl-ExtUtils-MakeMaker && \
    cd /tmp && \
    curl -LO https://github.com/git/git/archive/refs/tags/v2.43.0.tar.gz && \
    tar -xzf v2.43.0.tar.gz && \
    cd git-2.43.0 && \
    make prefix=/usr all && \
    make prefix=/usr install && \
    rm -rf /tmp/git-* && \
    yum clean all
7Fix Git version in CI/CD pipelines

Update your CI/CD configuration to use a recent Git version:

GitHub Actions:

yaml
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      # GitHub-hosted runners have recent Git, but you can update if needed:
      - name: Update Git
        run: |
          sudo add-apt-repository ppa:git-core/ppa -y
          sudo apt-get update
          sudo apt-get install -y git
          git --version
      - uses: actions/checkout@v4

GitLab CI:

yaml
default:
  image: ubuntu:22.04

before_script:
  - apt-get update && apt-get install -y software-properties-common
  - add-apt-repository ppa:git-core/ppa -y
  - apt-get update && apt-get install -y git
  - git --version

Jenkins:

groovy
pipeline {
    agent any
    stages {
        stage('Setup') {
            steps {
                sh '''
                    sudo add-apt-repository ppa:git-core/ppa -y
                    sudo apt-get update
                    sudo apt-get install -y git
                    git --version
                '''
            }
        }
    }
}
8Work around the issue without upgrading Git

If you cannot upgrade Git, you can work around the issue by modifying how Git is called:

Wrapper script approach:

bash
#!/bin/bash
# Save as /usr/local/bin/git-wrapper and make it executable
# This strips --no-optional-locks from arguments

args=()
for arg in "$@"; do
    if [[ "$arg" != "--no-optional-locks" ]]; then
        args+=("$arg")
    fi
done

/usr/bin/git "${args[@]}"

VS Code setting:
Add to your VS Code settings.json to use a different Git path or disable features requiring the flag:

json
{
  "git.path": "/path/to/newer/git",
  "git.useOptionalLocks": false
}

Note: VS Code's git.useOptionalLocks setting (if available in your version) controls whether --no-optional-locks is used.

Environment variable workaround:
Some tools check for Git version before using --no-optional-locks:

bash
# Fake Git version for tools that check (not recommended for production)
export GIT_VERSION_OVERRIDE="2.30.0"
9Verify PATH configuration

If you have multiple Git installations, ensure the correct one is used:

bash
# Find all Git installations
which -a git
type -a git

# Check PATH order
echo $PATH | tr ':' '\n' | head -20

# Common locations for Git:
# /usr/local/bin/git (compiled from source)
# /usr/bin/git (system package)
# /opt/homebrew/bin/git (Homebrew on Apple Silicon)
# /usr/local/bin/git (Homebrew on Intel Mac)

Ensure the newer Git appears first in PATH:

bash
# Add to ~/.bashrc or ~/.zshrc
export PATH="/usr/local/bin:$PATH"

# Apply changes
source ~/.bashrc

For system-wide configuration:

bash
# Create symlink to override system git
sudo ln -sf /usr/local/bin/git /usr/bin/git

Advanced notes

### About the --no-optional-locks Flag

The --no-optional-locks option was added in Git 2.15 to support better integration with file system watchers and IDE tools. Here's what it does:

bash
# Normal Git status acquires a lock
git status

# With --no-optional-locks, Git skips non-essential locks
git --no-optional-locks status

Why this flag exists:

1. File system watchers: IDEs like VS Code constantly poll Git status. Without this flag, each poll could block other Git operations
2. Network file systems: Lock files on NFS or SMB mounts can cause issues
3. Concurrent operations: CI/CD systems may run multiple Git commands simultaneously

### Git Version History Reference

| Git Version | Release Date | Notable Features |
|------------|--------------|------------------|
| 2.15 | Oct 2017 | --no-optional-locks added |
| 2.17 | Apr 2018 | Improved submodule support |
| 2.20 | Dec 2018 | Protocol v2 improvements |
| 2.22 | Jun 2019 | Partial clone support |
| 2.25 | Jan 2020 | Sparse checkout redesign |
| 2.30 | Dec 2020 | SHA-256 support |
| 2.38 | Oct 2022 | Scalar integrated |
| 2.43 | Nov 2023 | Performance improvements |

### Common OS Git Versions

| Operating System | Default Git Version | Notes |
|-----------------|---------------------|-------|
| Ubuntu 20.04 | 2.25.1 | Supports --no-optional-locks |
| Ubuntu 22.04 | 2.34.1 | Supports --no-optional-locks |
| Ubuntu 18.04 | 2.17.1 | Supports --no-optional-locks |
| CentOS 7 | 1.8.3 | Does NOT support --no-optional-locks |
| Amazon Linux 2 | 2.40+ | Supports --no-optional-locks |
| Alpine 3.14 | 2.32 | Supports --no-optional-locks |
| Debian 10 | 2.20.1 | Supports --no-optional-locks |
| macOS Monterey | 2.32+ | Supports --no-optional-locks |

### Checking Tool-Specific Configuration

VS Code:
VS Code uses --no-optional-locks by default when querying Git. Check the Git output channel for errors:
1. Open Command Palette (Ctrl+Shift+P)
2. Type "Git: Show Git Output"
3. Look for "unknown option" errors

npm/yarn:
Some Node.js tools use Git for version detection:

bash
# Check if npm is calling Git
npm config set loglevel verbose
npm install 2>&1 | grep -i git

Pre-commit hooks:
Check your .pre-commit-config.yaml or .husky configuration:

bash
# See what's calling Git in hooks
cat .git/hooks/pre-commit

### Building Git from Source (All Platforms)

For maximum control over Git version:

bash
# Download source
git clone https://github.com/git/git.git --depth 1 --branch v2.43.0
cd git

# Build with all features
make prefix=/usr/local all doc info
sudo make prefix=/usr/local install install-doc install-html install-info

# Verify
hash -r  # Clear command hash table
git --version

### Container Security Note

When building containers, prefer using official images with recent Git:

dockerfile
# Good: Use specific, recent base image
FROM node:20-bookworm

# Better: Use multi-stage build to minimize surface
FROM node:20-alpine AS builder
RUN apk add --no-cache git
# ... build steps ...

FROM node:20-alpine
COPY --from=builder /app /app

Frequently asked questions

What does "fatal: unknown option --no-optional-locks (git version too old)" mean?
15 (released October 2017). This flag tells Git to skip acquiring optional locks that could cause conflicts with concurrent processes or file system watchers. 15 and doesn't recognize this flag.
How do I fix "fatal: unknown option --no-optional-locks (git version too old)"?
The 'fatal: unknown option --no-optional-locks' error occurs when a tool or script invokes Git with the --no-optional-locks flag, but the installed Git version is too old to support this option. This typically happens in CI/CD pipelines, IDEs, or build systems that expect a newer Git version.
What causes "fatal: unknown option --no-optional-locks (git version too old)"?
Git version is older than 2.15 (released October 2017) CI/CD runner or container uses outdated base image with old Git System package manager provides outdated Git version
Is the "fatal: unknown option --no-optional-locks (git version too old)" error serious?
It is a low-severity error — more of a blocker than a risk. The steps above resolve it.

Official resources & further reading