Git LFS "git-lfs: command not found" / "lfs is not a git command"

Git LFS is a separate program from Git. When the runner only has Git, any LFS operation fails because the git-lfs binary is missing or was never initialized with git lfs install.

What this error means

A checkout or git lfs pull fails with git-lfs: command not found or git: 'lfs' is not a git command. Plain Git operations work; only LFS-specific commands fail.

git output

git: 'lfs' is not a git command. See 'git --help'.
# or, when the smudge filter runs:
git-lfs: command not found
error: external filter 'git-lfs filter-process' failed

Common causes

Git LFS is not installed on the runner

Slim or minimal runner images ship Git but not Git LFS. Without the git-lfs binary, the LFS subcommand and the smudge filter both fail.

LFS installed but not initialized

Even with the binary present, git lfs install must register the filters for this user/repo. Skipping it leaves LFS pointers unresolved.

How to fix it

Install and initialize Git LFS

Terminal

# Debian/Ubuntu
apt-get update && apt-get install -y git-lfs
git lfs install
git lfs pull

Enable LFS in the checkout action

On GitHub Actions, actions/checkout can fetch LFS content directly when LFS is available on the runner.

.github/workflows/ci.yml

- uses: actions/checkout@v4
  with:
    lfs: true

How to prevent it

Use a runner image that ships Git LFS, or install it in setup.
Run git lfs install once before any LFS operation.
Enable lfs: true in the checkout step for repos that use LFS.