gitpython

library3.1.46pypypi✓ verified 49d ago

GitPython is a Python library used to interact with Git repositories. The current version is 3.1.46, released on March 28, 2026. It follows a regular release cadence, with updates addressing bug fixes, feature enhancements, and security patches.

devops

pip install gitpython

github ↗package ↗

Install & Compatibility

Where this runs

tested against v3.1.50 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

glibc

py 3.10

3/5 runs

py 3.11

3/5 runs

py 3.12

3/5 runs

py 3.13

3/5 runs

py 3.9

3/5 runs

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

Repo

✓ from git import Repo

Ensure 'git' is the correct package name; 'gitpython' is the package name, but the import uses 'git'.

This script demonstrates how to initialize a Git repository and access the latest commit message using GitPython. Replace '/path/to/your/repo' with the actual path to your Git repository.

import os from git import Repo # Set the repository path repo_path = os.environ.get('REPO_PATH', '/path/to/your/repo') # Initialize the repository repo = Repo(repo_path) # Access the latest commit commit = repo.head.commit # Print the commit message print(f'Latest commit: {commit.message}')

git --version

Debug

Known issues

breakingGitPython requires Python 3.7 or higher. Attempting to use it with an older version will result in an ImportError.

fix

Upgrade your Python installation to version 3.7 or higher.

affects: all

gotchaEnsure that both 'gitdb' and 'smmap' are installed, as they are dependencies for GitPython. Missing these can lead to ImportError.

fix

Install the missing dependencies using pip: pip install gitdb smmap.

affects: all

breakingGitPython requires the 'git' command-line tool to be installed and accessible in the system's PATH, or its path explicitly configured. Missing 'git' will result in an ImportError.

fix

Ensure the 'git' command-line tool is installed and its executable is discoverable in the system's PATH. For example, on Debian/Ubuntu: `sudo apt-get update && sudo apt-get install git`. Alternatively, set the `GIT_PYTHON_GIT_EXECUTABLE` environment variable to the full path of the git executable.

affects: all

breakingGitPython requires the 'git' command-line tool to be installed on the system and accessible in the system's PATH, or explicitly configured. Failure to do so will result in an ImportError: Bad git executable.

fix

Ensure the 'git' command-line tool is installed on your system and available in the system's PATH. For Alpine Linux, use `apk add git`. For Debian/Ubuntu, use `apt-get install git`. Alternatively, set the environment variable `GIT_PYTHON_GIT_EXECUTABLE` to the full path of the git executable.

affects: all

Errors

Common errors & fixes

ModuleNotFoundError: No module named 'git'

This error occurs because the `gitpython` library is installed, but Python attempts to import a module literally named 'git', which is the top-level package name for the GitPython library, instead of the library's entry point.

fix

Ensure GitPython is installed with `pip install GitPython` and then import `Repo` or other classes directly from the `git` package, or use `import git` if you intend to use the top-level namespace.

ImportError: Failed to initialize: Bad git executable. The git executable must be specified in one of the following ways:...

GitPython requires the underlying Git command-line tool to be installed and accessible in the system's PATH. This error indicates that GitPython cannot locate the `git` executable.

fix

Install Git (the command-line tool) on your system and ensure its executable is included in your system's PATH. Alternatively, set the `GIT_PYTHON_GIT_EXECUTABLE` environment variable to the full path of the git executable, or explicitly set it in your Python code using `git.refresh(path='/path/to/git')`.

git.exc.GitCommandError: 'git clone ...' returned exit status 128: remote: Repository not found

This error indicates that the remote Git repository specified in the clone URL does not exist or the URL is incorrect.

fix

Verify that the repository URL is correct and that the repository actually exists at that location. Pay attention to typos, case sensitivity, and network connectivity.

git.exc.GitCommandError: 'git clone ...' returned exit status 128: fatal: Authentication failed for 'https://...' / fatal: could not read Username for 'https://...': No such device or address

This error signifies that GitPython, when attempting to clone or interact with a remote repository, encountered an authentication failure. This is often due to incorrect credentials (username/password, personal access token, or SSH key issues) or insufficient permissions for the repository.

fix

Provide correct authentication credentials (e.g., embed them in the URL for HTTPS clones, use an SSH agent for SSH, or configure Git's credential helper). For HTTPS, if 2FA is enabled, use a personal access token instead of your password. For SSH, ensure your SSH keys are correctly set up and added to the remote server.

AttributeError: module 'git' has no attribute 'Repo'

This error typically occurs when there is a naming conflict, such as a local file named `git.py` in the same directory as your script, which 'shadows' the actual installed `git` package from GitPython. It can also occur if GitPython was not correctly installed or if the Python environment is misconfigured.

fix

Rename any local file or directory named `git.py` or `git` that might be conflicting with the installed GitPython library. Ensure GitPython is properly installed and your Python environment's `sys.path` is correctly configured.

Upgrade

Version history

3.1.50latest on PyPI

Audit

Dependencies

gitdbrequiredRequired for GitPython's functionality

smmaprequiredRequired for GitPython's functionality

Agent activity

34 hits · last 30 days

mj12bot

seranking-bot

petalbot

amazonbot

node

ahrefsbot

Resources

githubhttps://github.com/gitpython-developers/GitPython ↗

packagehttps://pypi.org/project/gitpython/ ↗