---
id: git-filter-repo
version: "2.47.0"
license: MIT
license_treatment: permissive
maintenance: active
---

# git-filter-repo — Quickly rewrite git repository history

License: permissive · Maintenance: active · Downloads: 940.5K/mo

## What it is and what it does

git-filter-repo is a command-line tool and Python library for rewriting git repository history. It handles tasks like removing files, renaming paths, extracting subdirectories, and cleaning sensitive data across all commits. The tool is designed as a modern replacement for git filter-branch, which the git project itself now recommends against due to poor performance and safety issues.

Most users interact with it as a CLI tool with flags for common rewrites. For specialized needs, the package also exposes a library interface so developers can build custom history rewriting tools. It requires git >= 2.22.0 and Python >= 3.6, and has no external Python dependencies beyond the standard library.

Use it for:

- Remove accidentally committed secrets, large files, or sensitive data from all commits in a repository's history.
- Extract a subdirectory from a monorepo into a standalone repository with clean history.
- Rename file paths or directory structures across an entire repository's commit history.
- Migrate repositories between hosting platforms while cleaning up or restructuring history.
- Build a custom history rewriting tool by leveraging the filter-repo library for domain-specific transformations.

## Worth the install?

AI-flagged interpretation of the facts above — verify before relying.

Rewrites git repository history efficiently, replacing files, removing sensitive data, extracting subdirectories, and renaming paths across commits—faster and more capable than git filter-branch.

Yes. It is actively maintained, has no dependencies, installs easily, and solves a real problem (git history rewriting) that git filter-branch handles poorly. The MIT license is permissive. No known vulnerabilities. Recommended by the git project itself as the successor to filter-branch. Install if you need to rewrite git history or build tools that do so.

## Install

pip install git-filter-repo
uv add git-filter-repo
poetry add git-filter-repo

## Installing git-filter-repo

Before you install: Low friction: pure Python wheel with no runtime dependencies. Active maintenance (last commit 2026-07-09) and stable release cycle. Supports Python 3.6 through 3.12 and PyPy.

License in practice: MIT license (permissive): you can use, modify, and distribute freely with minimal restrictions. No copyleft obligations.

Quickstart:

pip install git-filter-repo

git filter-repo --path src/ --path-rename src/:my-module/

Requires git >= 2.22.0 (some features need >= 2.24.0) and Python 3 >= 3.6; git must be installed and in PATH.

Verify before relying:

- Whether the library API (for creating custom history rewriting tools) is stable and well-documented for programmatic use beyond the CLI.
- Performance characteristics on very large repositories (commit count, object count) compared to stated claims.

## Package facts

- License: MIT (permissive)
- Python support: supports_current
- Install friction: low
- Maintenance: active
- Downloads: 940.5K/month (top 5,000 on PyPI)
- Known vulnerabilities: none known

## Tags

git history rewriting, remove files from git history, extract git subdirectory, clean sensitive data from repo, git repository migration, bulk rename git paths, filter git commits, git-tools, history-rewriting, devops

[View on SkillFed](https://skillfed.io/packages/git-filter-repo) · [View on PyPI](https://pypi.org/project/git-filter-repo/)