I'm attempting to use git-filter-repo to remove large binaries from my repository. I have not used python before. I installed the latest python by clicking on the downloaded .exe file as that is a requirement of git-filter-repo. The instructions say:

git-filter-repo is a single-file python script, which was done to make installation for basic use trivial: just copy it into your $PATH


I have tried opening the git-filter-repo.py with the python application. I also can't use cd, ls, or dir in the python application.

  • 2
    The repo's INSTALL.md says to use your package manager, and lists a version for Ubuntu 20.04. I tried APT with no luck.
    – ndemarco
    Commented Jul 6, 2021 at 15:21
  • For Windows installation, these steps may help.
    – TTT
    Commented May 20, 2022 at 21:22

4 Answers 4


pip install

They now have a python package that just works:

python3 -m pip install --user git-filter-repo

That method installs both the command line executable, and the Python library which you can use as shown here.

The executable is named git-filter-repo, and Git automatically picks up any executable in PATH with name git-* on calls like git *, which is how this works.

Ubuntu 23.04

On this Ubuntu version or the one before, Ubuntu started adding the supremely annoying (but somewhat understandable) "error: externally-managed-environment" message to any pip install.

Thankfully they have a debian package for this one so you can:

sudo apt install git-filter-repo

Alternatively you can also override the error, or use a virtual environment, or the new pipx thing: https://stackoverflow.com/questions/75608323/how-do-i-solve-error-externally-managed-environment-every-time-i-use-pip-3

sudo apt install pipx
pipx install  git-filter-repo

which places the executable at ~/.local/bin/git-filter-repo.

I juts don't understand why pip stopped working with the good old --user, why do they keep changing the interface every two years!!!

Manual install

If for some reason you don't want to use pip, you can also just:

# Add to bashrc.
export PATH="${HOME}/bin:${PATH}"

mkdir -p ~/bin
wget -O ~/bin/git-filter-repo https://raw.githubusercontent.com/newren/git-filter-repo/7b3e714b94a6e5b9f478cb981c7f560ef3f36506/git-filter-repo
chmod +x ~/bin/git-filter-repo

Tested on Ubuntu 20.04, git-filter-repo ac039ecc095d.

  • 3
    I installed the package with pip in windows, but still get "git: 'filter-repo' is not a git command."
    – krenkz
    Commented Oct 6, 2020 at 18:01
  • 1
    @krenkz hi, this describes how Git finds stuff: gitirc.eu/howto/new-command.html Can you make sure that git-filter-repo it is either on PATH, or manually create a symlink in git -exec-path as mentioned at: superuser.com/a/1563783/128124 ? In Linux it just works because it goes to PATH. Commented Oct 6, 2020 at 19:25
  • 1
    I eventually just added git-filter-repo's location to the PATH and changed its first line to '#!/usr/bin/env py' and now it works fine - all done manually. Thanks!
    – krenkz
    Commented Oct 6, 2020 at 20:08
  • git filter-repo is a git command that tries to execute git-filter-repo. This will look for git-filter-repo in your $PATH (and other usual suspects?). Installing with pip may not put git-filter-repo.py into a place where git looks or may not make it executable.
    – CervEd
    Commented Sep 26, 2021 at 18:27
  • @CervEd do share OS and OS version if you came across a system where that happens Commented Sep 26, 2021 at 19:15

On a Mac, you can install it using homebrew:

$ brew install git-filter-repo

  • Also worked on WSL Ubuntu 20.04. Probably other versions, too, but this happens to be the one I am working with. Commented May 17, 2023 at 13:00

This is how I got it to work.

  1. Python should be installed and added to the system's path.
  2. Git should be installed and git also added to the system's path.
  3. Download git-filter-repo
  4. Replace 'python3' on first line of file called git-filter-repo with 'python'. Depending on your python installation, you may skip this step.
  5. Call git --exec-path
  6. Move the git-filter-repo file into that location shown. (git's path).
  7. To use, type git filter-repo. The help option will not work, but they have documentation online.

On a Mac, I simply downloaded https://github.com/newren/git-filter-repo/blob/main/git-filter-repo into my ~/local/bin (which was already on my path and where I keep all my batch files etc). After chmod +x git-filter-repo, I just ran it from my repo dir like: git-filter-repo --path mydir.

  • This was much easier than installing homebrew.
    – Paul Lynch
    Commented Feb 28, 2022 at 1:02
  • nice one. on linux i had to put the file in the same directory given by git --exec-path
    – Paolo
    Commented Apr 22, 2022 at 10:48

You must log in to answer this question.

Not the answer you're looking for? Browse other questions tagged .