Git LFS "git-lfs: command not found" from filter-process in CI

By Daniel Zoghalchali·Latchkey

git invoked the LFS filter but the git-lfs executable is not on the runner PATH. Without the binary, the smudge/clean filters cannot run and checkout of LFS files fails.

What this error means

checkout fails with "git: 'lfs' is not a git command" or "git-lfs: command not found", often as "error: external filter 'git-lfs filter-process' failed".

git-lfs

git: 'lfs' is not a git command. See 'git --help'.
error: external filter 'git-lfs filter-process' failed
fatal: assets/model.bin: smudge filter lfs failed

Common causes

git-lfs is not installed on the runner image

A slim or self-hosted image ships git but not the separate git-lfs package, so the filter command does not exist.

git-lfs is installed but not initialized

Even when the binary exists, git lfs install may not have registered the filters for the user running the job.

How to fix it

Install and initialize git-lfs

Install the git-lfs package on the runner.
Run git lfs install to register the smudge/clean filters.
Re-run the checkout so the filter resolves.

Terminal

sudo apt-get update && sudo apt-get install -y git-lfs
git lfs install

Use a runner image that bundles git-lfs

GitHub-hosted runners include git-lfs by default; for self-hosted or container jobs, bake it into the image so no per-job install is needed.

Using this in CI

CI checkouts are shallow and detached by default, which changes the answer this command gives you. Commands that read history, branch names, or tags need the checkout configured for it.

.github/workflows/ci.yml

- uses: actions/checkout@v4
  with:
    fetch-depth: 0   # history, tags, and git describe all need this

- run: |
    git rev-parse --is-shallow-repository   # expect false
    git rev-parse --abbrev-ref HEAD          # prints HEAD when detached

How to prevent it

Include git-lfs in self-hosted and container runner images.
Run git lfs install once during image setup.
Pin a git-lfs version so behavior is consistent across runners.

Frequently asked questions

What causes Git LFS "git-lfs: command not found" from filter-process in CI?

There are 2 common causes: git-lfs is not installed on the runner image and git-lfs is installed but not initialized. A slim or self-hosted image ships git but not the separate git-lfs package, so the filter command does not exist.

How do I fix Git LFS "git-lfs: command not found" from filter-process in CI?

There are 2 fixes depending on which cause you have: install and initialize git-lfs and use a runner image that bundles git-lfs. Work through them in order, since the first is the most common.

What does Git LFS "git-lfs: command not found" from filter-process in CI actually mean?