Installation

Prerequisites

Before installing git-filter-repo, ensure you have:

Git >= 2.36.0
Python >= 3.6

You can verify your versions with:

git --version
python3 --version

Installation Methods

Simple (Recommended)
Package Manager
PyPI (pipx/uv)
Makefile

The simplest way to install git-filter-repo is to download the single Python script.

Download the script

Download the git-filter-repo script from the repository:

curl -o git-filter-repo https://raw.githubusercontent.com/newren/git-filter-repo/main/git-filter-repo

Make sure to preserve the filename as git-filter-repo with no extension.

Make it executable

chmod +x git-filter-repo

Run the tool

You can now run it directly:

python3 git-filter-repo --analyze

Or place it in your $PATH to use the shorter syntax:

# Move to a directory in your PATH
sudo mv git-filter-repo /usr/local/bin/

# Now you can run it as:
git filter-repo --analyze

git-filter-repo is available through various package managers across different platforms.

macOS (Homebrew)

brew install git-filter-repo

Windows (Scoop)

scoop install git-filter-repo

Debian/Ubuntu

sudo apt-get install git-filter-repo

Fedora

sudo dnf install git-filter-repo

Arch Linux

sudo pacman -S git-filter-repo

For a complete list of available packages, see Repology.

Install git-filter-repo as a Python package using pipx or uv tool.

pipx install git-filter-repo

Using pipx or uv tool is recommended over pip to avoid conflicts with system Python packages.

For manual installation with full control over paths:

Clone the repository

git clone https://github.com/newren/git-filter-repo.git
cd git-filter-repo

Get documentation (optional)

If installing from a git clone, you may want the documentation:

make snag_docs

This copies the generated documentation files from the docs branch.

Install with make

sudo make prefix=/usr pythondir=/usr/lib64/python3.8/site-packages install

Replace the pythondir value with your Python site-packages directory. Find it with:

python3 -c "import site; print(site.getsitepackages())"

The Makefile will not edit the shebang line if your Python executable is not named python3. You’ll need to manually edit the first line of git-filter-repo if needed.

Advanced Installation (For Library Use)

If you want to use git-filter-repo as a Python library or use contrib scripts:

Create git_filter_repo.py

Create a symlink or copy of git-filter-repo named git_filter_repo.py:

ln -s git-filter-repo git_filter_repo.py
# or
cp git-filter-repo git_filter_repo.py

Place in Python path

Place git_filter_repo.py in your Python site-packages or anywhere in $PYTHONPATH:

SITE_PACKAGES=$(python3 -c "import site; print(site.getsitepackages()[-1])")
sudo cp git_filter_repo.py $SITE_PACKAGES/

Platform-Specific Notes

Windows Users

Windows can present some unique challenges:

Non-functional Python Stub

Windows sometimes ships with a non-functional Python stub that can cause the application to hang. Install Python from the Microsoft Store.

Python Executable Name

If your Python executable is named python instead of python3, you have two options:

Edit the first line of git-filter-repo to use python instead of python3
Use the full form in commands: python git-filter-repo instead of git filter-repo

Symlink Issues

If git_filter_repo.py appears as a regular file with just one line instead of a proper symlink, delete it and create a copy instead:

del git_filter_repo.py
copy git-filter-repo git_filter_repo.py

Verification

Verify your installation by running:

git filter-repo --version

Or display the help:

git filter-repo -h

What Gets Installed

A complete installation includes:

git-filter-repo

The main executable script. Required for all use cases.

git_filter_repo.py

Python library module. Optional, needed for using filter-repo as a library.

git-filter-repo.1

Man page. Optional, enables git filter-repo --help on Linux/Mac.

git-filter-repo.html

HTML documentation. Optional, enables git filter-repo --help on Windows.

Next Steps

Quickstart

Try your first repository filtering

Analyzing Repositories

Analyze your repo to decide what to filter

Getting Started

Core Concepts

Common Use Cases

Guides

Migration Guides

Examples

Resources

Prerequisites

Installation Methods

Advanced Installation (For Library Use)

Platform-Specific Notes

Non-functional Python Stub

Python Executable Name

Symlink Issues

Verification

What Gets Installed

git-filter-repo

git_filter_repo.py

git-filter-repo.1

git-filter-repo.html

Next Steps

Quickstart

Analyzing Repositories

Build docs developers (and LLMs) love

Getting Started

Core Concepts

Common Use Cases

Guides

Migration Guides

Examples

Resources

​Prerequisites

​Installation Methods

​Advanced Installation (For Library Use)

​Platform-Specific Notes

​Non-functional Python Stub

​Python Executable Name

​Symlink Issues

​Verification

​What Gets Installed

git-filter-repo

git_filter_repo.py

git-filter-repo.1

git-filter-repo.html

​Next Steps

Quickstart

Analyzing Repositories

Build docs developers (and LLMs) love

Prerequisites

Installation Methods

Advanced Installation (For Library Use)

Platform-Specific Notes

Non-functional Python Stub

Python Executable Name

Symlink Issues

Verification

What Gets Installed

Next Steps