# How to Enable Git LFS Support in actions/checkout: Complete Implementation Guide

> Easily enable Git LFS support in actions/checkout by setting lfs: true. This guide shows how to automatically install the LFS client and fetch large files for your CI/CD workflows.

- Repository: [GitHub Actions/checkout](https://github.com/actions/checkout)
- Tags: how-to-guide
- Published: 2026-07-05

---

**Set `lfs: true` in your workflow configuration to enable Git LFS support, which automatically installs the LFS client and fetches large files during the checkout process.**

The `actions/checkout` action supports repositories that use Git Large File Storage (LFS) through an optional boolean input. When enabled, the action handles the complete LFS workflow—from client installation to object fetching—without requiring manual Git commands in your workflow.

## How Git LFS Support Works Internally

The LFS implementation follows a clear pipeline through the action's TypeScript source code. Understanding this flow helps debug issues and optimize performance.

### Input Parsing and Validation

The process begins in [`src/input-helper.ts`](https://github.com/actions/checkout/blob/main/src/input-helper.ts), where the action reads the `lfs` input from your workflow and converts it to a boolean:

```typescript
// src/input-helper.ts (lines 22-24)
result.lfs = (core.getInput('lfs') || 'false').toUpperCase() === 'TRUE'

```

This parses the string input and defaults to `false` if the parameter is omitted, ensuring backward compatibility for existing workflows.

### Command Manager Initialization

The parsed flag propagates to [`src/git-source-provider.ts`](https://github.com/actions/checkout/blob/main/src/git-source-provider.ts), which creates a specialized Git command manager that understands LFS operations:

```typescript
// src/git-source-provider.ts (lines 73-80)
return await gitCommandManager.createCommandManager(
    settings.repositoryPath,
    settings.lfs,
    settings.sparseCheckout != null
)

```

The second parameter (`settings.lfs`) tells the manager to prepare for LFS operations.

### LFS Client Installation and Fetching

After repository initialization, the provider conditionally installs the LFS client and fetches large files:

```typescript
// src/git-source-provider.ts (lines 69-72)
if (settings.lfs) {
    await git.lfsInstall()
}

```

Then, during the fetch phase:

```typescript
// src/git-source-provider.ts (lines 46-49)
if (settings.lfs && !settings.sparseCheckout) {
    await git.lfsFetch(checkoutInfo.startPoint || checkoutInfo.ref)
}

```

The `lfsFetch` method retrieves the actual large file objects from your LFS server, making them available in your working directory.

### Error Handling for Missing Dependencies

If Git or the LFS component is not available on the runner, the action fails early with a clear error:

```typescript
// src/git-source-provider.ts (lines 84-88)
if (settings.lfs) {
    throw err   // re-throw when LFS is requested but Git isn't present
}

```

This prevents workflows from proceeding with corrupted or incomplete file data.

## Configuring Git LFS in Your Workflow

Enable LFS support by adding the `lfs` parameter to your checkout step:

```yaml

# .github/workflows/build.yml

name: Build with LFS
on: [push]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout repository with LFS
        uses: actions/checkout@v4
        with:
          lfs: true
          fetch-depth: 0

```

**Key configuration points:**

- **Default behavior**: The `lfs` input defaults to `false` as defined in [`action.yml`](https://github.com/actions/checkout/blob/main/action.yml)
- **Fetch depth**: Use `fetch-depth: 0` for full history or keep the default `fetch-depth: 1` if you only need the latest LFS objects
- **Runner requirements**: The Git LFS client must be installed on the runner (pre-installed on GitHub-hosted runners)

## Performance and Compatibility Considerations

The LFS implementation in `actions/checkout` differs from standard Git operations in several ways:

- **Parallel fetching**: LFS objects are fetched in parallel where possible, optimizing download times for repositories with multiple large files
- **Sparse checkout limitation**: When `sparseCheckout` is configured, the action skips the automatic `lfsFetch` call (lines 46-49), requiring manual LFS operations if needed
- **Storage impact**: Large files consume bandwidth and storage quotas on your LFS server with each fetch

## Summary

- **Enable LFS** by setting `lfs: true` in your `actions/checkout` step configuration
- **Automatic installation** occurs via `git.lfsInstall()` in [`src/git-source-provider.ts`](https://github.com/actions/checkout/blob/main/src/git-source-provider.ts)
- **Object fetching** runs automatically via `git.lfsFetch()` for non-sparse checkouts
- **Error handling** prevents silent failures when Git LFS is unavailable on the runner
- **Source files** involved include [`src/input-helper.ts`](https://github.com/actions/checkout/blob/main/src/input-helper.ts), [`src/git-source-provider.ts`](https://github.com/actions/checkout/blob/main/src/git-source-provider.ts), and [`src/git-command-manager.ts`](https://github.com/actions/checkout/blob/main/src/git-command-manager.ts)

## Frequently Asked Questions

### What happens if Git LFS is not installed on the runner?

The action throws an error and fails immediately. According to the source code in [`src/git-source-provider.ts`](https://github.com/actions/checkout/blob/main/src/git-source-provider.ts) (lines 84-88), when `settings.lfs` is true but the Git command manager fails to initialize, the error is re-thrown to prevent the workflow from continuing with missing large files.

### Does enabling LFS affect checkout performance?

Yes, enabling LFS adds network overhead because the action must fetch large file objects from your LFS server after the initial Git clone. The implementation attempts to optimize this by running `git lfs fetch` in parallel where possible, but repositories with many large files will see increased checkout times proportional to the total data size.

### Can I use LFS with sparse checkout?

You can enable both features simultaneously, but the automatic LFS fetch is disabled when sparse checkout is active. As shown in lines 46-49 of [`src/git-source-provider.ts`](https://github.com/actions/checkout/blob/main/src/git-source-provider.ts), the condition `!settings.sparseCheckout` prevents the automatic `lfsFetch` call. You must manually run `git lfs fetch` after the checkout step if you need large files within your sparse checkout patterns.

### What is the default value for the lfs input?

The `lfs` input defaults to `false` as defined in the [`action.yml`](https://github.com/actions/checkout/blob/main/action.yml) file. This means you must explicitly set `lfs: true` to enable Git LFS support; otherwise, the action skips all LFS-related operations and large files will remain as pointer files in your working directory.