How to fix error: sparse-checkout is not supported in this CI environment in Git

What this error means

This error message appears when a CI/CD pipeline attempts to use the `git sparse-checkout` command, but the Git version installed in the CI environment doesn't support it. The `git sparse-checkout` subcommand was introduced in **Git 2.25.0** (January 2020), so any environment running an older Git version will fail with this error. The error commonly manifests in several forms: - `git: 'sparse-checkout' is not a git command. See 'git --help'` - `error: sparse-checkout is not supported in this CI environment` - `Error: The process '/usr/bin/git' failed with exit code 1` This is particularly common when using Docker containers with older base images (like `python:2.7.18-buster`) or CI runners that haven't been updated recently. The error can also occur when CI tools like GitHub Actions' `actions/checkout@v4` attempt to use sparse-checkout features unconditionally, without first checking Git version compatibility. While sparse-checkout functionality existed in Git prior to version 2.25 via the `core.sparseCheckout` config option, the convenient `git sparse-checkout` command is only available in newer versions.

Typical symptoms

• 'sparse-checkout' is not a git command error in CI pipeline logs
• GitHub Actions workflow fails at checkout step with sparse-checkout error
• Jenkins pipeline fails when using sparse checkout extension
• GitLab CI job fails during repository clone or checkout phase
• Azure DevOps pipeline errors when attempting partial repository checkout
• Docker-based CI builds fail with git sparse-checkout commands
• actions/checkout@v4 fails with 'git sparse-checkout disable' error
• CI works locally but fails on the build server

Common causes

1. Git version in CI environment is older than 2.25.0 (sparse-checkout command not available)
2. Docker container base image includes an outdated Git installation
3. CI tool (like actions/checkout v4) unconditionally uses sparse-checkout without version check
4. Self-hosted CI runners haven't been updated with recent Git versions
5. Using legacy Linux distributions (Debian Buster, Ubuntu 18.04) with old Git packages
6. Git version between 2.25 and 2.28 missing extensions.partialClone configuration
7. CI environment uses system Git instead of a newer manually installed version
8. Container image was built before Git 2.25 release and hasn't been updated

How to fix "error: sparse-checkout is not supported in this CI environment"

# GitHub Actions
- name: Check Git version
  run: git --version

# GitLab CI
check_git:
  script:
    - git --version

# Jenkins (Groovy)
sh 'git --version'

# Azure DevOps
- script: git --version

- name: Install latest Git
  run: |
    sudo add-apt-repository ppa:git-core/ppa -y
    sudo apt-get update
    sudo apt-get install git -y
    git --version

# Add git-core PPA and install latest Git
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/*

# Alpine usually has recent Git versions
RUN apk add --no-cache git

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

# Enable sparse checkout via config
git config core.sparseCheckout true

# Create sparse-checkout patterns file
mkdir -p .git/info
echo 'path/to/directory/' >> .git/info/sparse-checkout
echo 'another/path/' >> .git/info/sparse-checkout

# Apply the sparse checkout
git read-tree -mu HEAD

- name: Checkout with legacy sparse-checkout
  run: |
    git clone --no-checkout --depth 1 ${{ github.server_url }}/${{ github.repository }}.git .
    git config core.sparseCheckout true
    echo 'src/' >> .git/info/sparse-checkout
    echo 'package.json' >> .git/info/sparse-checkout
    git checkout ${{ github.sha }}

# v4 may fail on old Git; v3 is more compatible
- uses: actions/checkout@v3

- uses: actions/checkout@v4
  with:
    sparse-checkout: ""  # Explicitly disable sparse-checkout

checkout([
    $class: 'GitSCM',
    extensions: [[$class: 'SparseCheckoutPaths',
                  sparseCheckoutPaths: [[path: 'src/']]]]
])

# Instead of older images
# FROM python:2.7.18-buster  # Has old Git

# Use newer base images
FROM python:3.11-bookworm    # Debian 12, Git 2.39+
FROM ubuntu:22.04            # Git 2.34+
FROM ubuntu:24.04            # Git 2.43+

FROM python:3.9-slim AS base

# Install newer Git
RUN apt-get update && \
    apt-get install -y --no-install-recommends \
    software-properties-common && \
    add-apt-repository ppa:git-core/ppa -y && \
    apt-get update && \
    apt-get install -y --no-install-recommends git && \
    rm -rf /var/lib/apt/lists/*

# Required for --filter option with git fetch in older versions
git config extensions.partialClone origin

# Then you can use partial clone with sparse-checkout
git clone --filter=blob:none --no-checkout <url>
git sparse-checkout init --cone
git sparse-checkout set path/to/dir
git checkout main

- uses: actions/checkout@v4
  with:
    sparse-checkout: |
      src
      package.json
    sparse-checkout-cone-mode: true
    filter: blob:none

# Clone only recent history
git clone --depth 1 <repository-url>
# Remove unwanted directories after clone
rm -rf unwanted-dir/

# Download specific directory as archive (works with remote repos)
git archive --remote=<repository-url> HEAD:path/to/dir | tar -x

variables:
  GIT_STRATEGY: none

job:
  script:
    - git init
    - git remote add origin $CI_REPOSITORY_URL
    - git config core.sparseCheckout true
    - echo "src/" >> .git/info/sparse-checkout
    - git fetch --depth 1 origin $CI_COMMIT_SHA
    - git checkout FETCH_HEAD

- checkout: none
- script: |
    git init
    git remote add origin $(Build.Repository.Uri)
    git config core.sparseCheckout true
    echo "src/" >> .git/info/sparse-checkout
    git fetch --depth 1 origin $(Build.SourceVersion)
    git checkout FETCH_HEAD

Advanced notes

# Full Git environment info
git --version
git config --list --show-origin

# Check if sparse-checkout command exists
git sparse-checkout 2>&1 | head -5

# Verify extensions support
git config --get extensions.partialClone

# List available Git commands
git --list-cmds=main,others | grep sparse

git clone --filter=blob:none --depth=1 --sparse <url>
git sparse-checkout set path/to/needed/files

# GitHub Actions
on:
  push:
    paths:
      - 'packages/my-app/**'

jobs:
  build:
    steps:
      - uses: actions/checkout@v4
        with:
          sparse-checkout: |
            packages/my-app
            packages/shared
          sparse-checkout-cone-mode: true

- name: Checkout (try modern, fallback to legacy)
  run: |
    git clone --no-checkout $REPO_URL .
    if git sparse-checkout init --cone 2>/dev/null; then
      git sparse-checkout set src/ package.json
    else
      git config core.sparseCheckout true
      echo 'src/' >> .git/info/sparse-checkout
      echo 'package.json' >> .git/info/sparse-checkout
    fi
    git checkout HEAD

Frequently asked questions

What does "error: sparse-checkout is not supported in this CI environment" mean?

This error message appears when a CI/CD pipeline attempts to use the git sparse-checkout command, but the Git version installed in the CI environment doesn't support it. 0 (January 2020), so any environment running an older Git version will fail with this error. The error commonly manifests in several forms: - git: 'sparse-checkout' is not a git command.

How do I fix "error: sparse-checkout is not supported in this CI environment"?

This error occurs when your CI environment's Git version is too old to support the sparse-checkout command. The git sparse-checkout subcommand requires Git 2.25 or newer. Upgrade Git in your CI environment or use the legacy sparse-checkout configuration method.

What causes "error: sparse-checkout is not supported in this CI environment"?

Git version in CI environment is older than 2.25.0 (sparse-checkout command not available) Docker container base image includes an outdated Git installation CI tool (like actions/checkout v4) unconditionally uses sparse-checkout without version check

Is the "error: sparse-checkout is not supported in this CI environment" error serious?

It is a medium-severity error — more of a blocker than a risk. The steps above resolve it.

Related errors

• fatal: Authentication failed - CI token expired during long build

  How to fix 'CI token expired during long build' in Git

  MEDIUM

• fatal: git fetch-pack: expected shallow list. Shallow clone may not have all commits

  How to fix 'expected shallow list' and shallow clone missing commits in Git

  MEDIUM

• Permission denied (publickey). CircleCI checkout key may be invalid or revoked

  How to fix 'Permission denied (publickey). CircleCI checkout key may be invalid or revoked' in Git

  MEDIUM

• fatal: couldn't find remote ref

  How to fix 'Couldn't find remote ref' in Git

  MEDIUM

• API rate limit exceeded

  How to fix 'API rate limit exceeded' in GitHub

  MEDIUM

• fatal: destination path already exists and is not an empty directory

  Destination Path Already Exists and Is Not Empty

  LOW

Official resources & further reading

• 📚Git Official Documentation
• 📖
  Git sparse-checkout Documentation(Official Docs)
• 🐙
  GitHub Actions checkout sparse-checkout issue(GitHub)
• 🐙
  Sparse checkout not working with git 2.25-2.28(GitHub)
• 💬
  Stack Overflow - Jenkins and Git sparse checkouts(Stack Overflow)
• 💬
  Stack Overflow - GitLab CI sparse checkout(Stack Overflow)
• 📝
  InfoQ - Git 2.25 Improves Support for Sparse Checkout
• 📖
  Jenkins Git Plugin Documentation(Official Docs)