gitoxide-python

PyPI Version CI

Fast, safe, pure-Rust Git for Python — bindings to the gitoxide engine, and a modern alternative to GitPython.

gitoxide (the gix crate) is a next-generation, pure-Rust implementation of Git. This project exposes that engine to Python through PyO3 and ships as pre-built wheels via maturin, so you get:

GitPython pygit2 gitoxide-python
Backend shells out to the git CLI C libgit2 pure-Rust gix
Speed slow (spawns a subprocess per call) fast fast (in-process, no subprocess)
Install needs git on PATH needs a C toolchain / system libgit2 pip install, self-contained wheels
Memory safety n/a (subprocess) C Rust

"No subprocess" refers to the git CLI: nothing here shells out to git. A repository that configures a clean/smudge filter (Git LFS, say) will still have that filter program executed when blame reads such a file — exactly as git itself would.

Status: alpha. The binding surface is small but real. It currently covers read-oriented workflows (open/discover, HEAD, history walk, refs, branches, tags, blob reads) — the operations DevOps tooling reaches for most. See Scope for what is and isn't wrapped yet.

Installation

pip install gitoxide

Pre-built wheels are published for Linux (manylinux, x86_64 + aarch64), macOS (x86_64 + Apple Silicon), and Windows — no Rust toolchain or system libgit2 required.

Quick start

import gitoxide

repo = gitoxide.open(".")            # or gitoxide.discover(".")

print(repo.git_dir)                  # .../my-project/.git
print(repo.workdir)                  # .../my-project  (None if bare)
print(repo.is_bare)                  # False
print(repo.head_name)                # 'main'  (None if detached)

# The commit at HEAD
head = repo.head_commit()
print(head.short_id, head.summary)
print(head.author.name, head.author.email, head.author.time)

# Walk history (reverse-chronological), like `git log`
for commit in repo.commits(max_count=10):
    print(commit.short_id, commit.author.name, commit.summary)

# Resolve a revspec to an object id
print(repo.rev_parse("HEAD~2"))
print(repo.rev_parse("main"))

# Branches, tags, and all references
print(repo.branches())               # ['main', 'dev', ...]
print(repo.tags())                   # ['v1.0.0', ...]
for ref in repo.references():
    print(ref.name, "->", ref.target)

# Read a file's content at a revision
readme = repo.read_blob("HEAD:README.md")
print(readme.decode())

# Blame a file: which commit last touched each line
for hunk in repo.blame("README.md"):
    print(f"{hunk.start_line}-{hunk.end_line}\t{hunk.short_id}")

Migrating from GitPython

Common operations, side by side:

GitPython gitoxide-python
from git import Repo import gitoxide
repo = Repo(path) repo = gitoxide.open(path)
Repo(path, search_parent_directories=True) gitoxide.discover(path)
repo.head.commit repo.head_commit()
repo.active_branch.name repo.head_name
repo.iter_commits("main", max_count=10) repo.commits("main", max_count=10)
repo.commit("HEAD~2") repo.commit("HEAD~2")
repo.rev_parse("main").hexsha repo.rev_parse("main")
[b.name for b in repo.branches] repo.branches()
[t.name for t in repo.tags] repo.tags()
c.hexsha, c.summary, c.author.name c.id, c.summary, c.author.name

The key difference is what happens underneath: GitPython's iter_commits spawns a git rev-list subprocess; gitoxide-python walks the object database in-process in Rust.

API

Module functions

  • gitoxide.open(path) -> Repository
  • gitoxide.discover(path) -> Repository — search path and its parents
  • gitoxide.init(path, bare=False) -> Repository
  • gitoxide.gix_version() -> str

Repository

Properties: git_dir, workdir, is_bare, is_shallow, head_id, head_name, head_is_detached.

Note: head_name and head_is_detached access the HEAD reference and may raise GitoxideError if it is inaccessible (e.g., corrupted repository). Other properties never raise.

Methods: head_commit(), rev_parse(spec), commit(rev), commits(rev=None, max_count=None), references(), branches(), tags(), read_blob(rev), blame(path, rev=None).

Commit

id, short_id, tree_id, message, summary, author, committer, parents.

Signature

name, email, time (Unix seconds), offset (UTC offset seconds).

Reference

name, shorthand, target.

BlameHunk

start_line, end_line, line_count, orig_start_line, commit_id, short_id. Line numbers are 1-based and inclusive, matching git blame. Consecutive lines from the same commit are grouped into one hunk.

All errors (from any function or method) are raised as gitoxide.GitoxideError.

Scope

This is a binding, not a reimplementation: it exposes a slice of what the gix engine already does. Today that slice is:

  • Wrapped: open / discover / init, HEAD, history walk, rev-parse, references, branches, tags, blob reads, and blame.
  • Not wrapped yet: diff & status, tree listing, writing commits and the index, and clone / remote operations.

The engine supports much more; these are simply the parts this binding hasn't surfaced yet. Issues and pull requests that expose more of gix are welcome — see Contributing.

Contributing

The binding layer lives in a single src/lib.rs and maps closely onto the gix API, so adding a method is usually a small, self-contained change.

Building from source requires a Rust toolchain (this is also the path used when installing the sdist on a platform without a pre-built wheel):

python -m venv .venv && source .venv/bin/activate
pip install maturin pytest

maturin develop          # build the extension into the venv
pytest -q                # run the test suite

cargo fmt --all          # format Rust
cargo clippy --all-targets -- -D warnings

The tests generate a throwaway git repository on the fly (see tests/conftest.py), so they need git on PATH but touch nothing outside a temp directory.

License

Licensed under either of Apache License 2.0 or MIT license at your option, to match the upstream gitoxide project.

Project links

Data verified by PyPI on Sep 1, 2026
Data provided by the project maintainers, verified at the time the release was uploaded to PyPI.

Key dates

PyPI data
Data sourced directly from PyPI's database.
  • Released:
Latest release

1 maintainer

PyPI data
Data sourced directly from PyPI's database.
Avatar for xpshen from gravatar.com xpshen

Credits

PyPI data
Data sourced directly from PyPI's database.

Author: Xianpeng Shen

GitHub Statistics

Data verified by PyPI on Sep 1, 2026
The GitHub source repository was provided by the project maintainers and verified by PyPI at the time of upload. Stars, forks, and open issues/PRs are derived from that repository and have not been independently verified.

License expression

MIT OR Apache-2.0
View SPDX License List

Requires

Python >=3.9

Provides Extra

test

Tags

git gitoxide gix vcs version-control gitpython

Classifiers

Report project as malware

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

gitoxide-0.4.0.tar.gz (30.7 kB view details)

Uploaded Source

Built Distributions

If you're not sure about the file name format, learn more about wheel file names.

gitoxide-0.4.0-cp39-abi3-win_amd64.whl (2.1 MB view details)

Uploaded CPython 3.9+Windows x86-64

gitoxide-0.4.0-cp39-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (2.2 MB view details)

Uploaded CPython 3.9+manylinux: glibc 2.17+ x86-64

gitoxide-0.4.0-cp39-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl (2.2 MB view details)

Uploaded CPython 3.9+manylinux: glibc 2.17+ ARM64

gitoxide-0.4.0-cp39-abi3-macosx_11_0_arm64.whl (2.1 MB view details)

Uploaded CPython 3.9+macOS 11.0+ ARM64

gitoxide-0.4.0-cp39-abi3-macosx_10_12_x86_64.whl (2.1 MB view details)

Uploaded CPython 3.9+macOS 10.12+ x86-64

File details

Details for the file gitoxide-0.4.0.tar.gz.

File metadata

  • Download URL: gitoxide-0.4.0.tar.gz
  • Upload date:
  • Size: 30.7 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for gitoxide-0.4.0.tar.gz
Algorithm Hash digest
SHA256 c1e613b0236e5ad24515c0ba725a47bd97b4b16d8f1b67e901d971630e6fccf5
MD5 fd58b9ebd1b1c74677d2347c650cdf41
BLAKE2b-256 4fdbd9743856c9b9511794c0bdbf487f4243abab240ac137dab9a9ea9dff64fc

See more details on using hashes here.

Provenance

The following attestation bundles were made for gitoxide-0.4.0.tar.gz:

Publisher: publish.yml on shenxianpeng/gitoxide

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file gitoxide-0.4.0-cp39-abi3-win_amd64.whl.

File metadata

  • Download URL: gitoxide-0.4.0-cp39-abi3-win_amd64.whl
  • Upload date:
  • Size: 2.1 MB
  • Tags: CPython 3.9+, Windows x86-64
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for gitoxide-0.4.0-cp39-abi3-win_amd64.whl
Algorithm Hash digest
SHA256 23a2e8ee240dc51dec4f254265a297ee6c6045a683478ba782244da4237fd301
MD5 e8a05b01d077061aac190c07007c7f56
BLAKE2b-256 76638a85ebf15b43bc8ae0fb1c30bc709b79b4ecbcd5360e6a9eb08dd710247d

See more details on using hashes here.

Provenance

The following attestation bundles were made for gitoxide-0.4.0-cp39-abi3-win_amd64.whl:

Publisher: publish.yml on shenxianpeng/gitoxide

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file gitoxide-0.4.0-cp39-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl.

File metadata

File hashes

Hashes for gitoxide-0.4.0-cp39-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm Hash digest
SHA256 f72817d3c6e7052269c45fb636c2d338c9ad1871cfb1999848973a5352aebd41
MD5 b02a0d8927f09ccd9c7f3d0d4f508858
BLAKE2b-256 14fc1d0dd417a323cc3112f32bc90a0f567673e0cf37955366b9239f11fe4ea2

See more details on using hashes here.

Provenance

The following attestation bundles were made for gitoxide-0.4.0-cp39-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl:

Publisher: publish.yml on shenxianpeng/gitoxide

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file gitoxide-0.4.0-cp39-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl.

File metadata

File hashes

Hashes for gitoxide-0.4.0-cp39-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
Algorithm Hash digest
SHA256 bc2500944c68d12dfe71f674adda0cb541d388b294908e767e6f21bc466ee663
MD5 66ca7a5dbd9bff2249a65df5a1320aa2
BLAKE2b-256 e1a95c45ebd7b3422164250d2c41b589baf52d2caad9d376ff6bb3dc7fd21684

See more details on using hashes here.

Provenance

The following attestation bundles were made for gitoxide-0.4.0-cp39-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl:

Publisher: publish.yml on shenxianpeng/gitoxide

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file gitoxide-0.4.0-cp39-abi3-macosx_11_0_arm64.whl.

File metadata

File hashes

Hashes for gitoxide-0.4.0-cp39-abi3-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 4ad564a8ab631918a4474a8c40a5771d6a66861f80fb4522be7bd1616c2eecae
MD5 63e0806eabbf4d0df0f1c2f6f874fb84
BLAKE2b-256 6dc6c304cea613fe5b0346ceffc63b9c3afb414a220314b6ae59751f6e5ec9ab

See more details on using hashes here.

Provenance

The following attestation bundles were made for gitoxide-0.4.0-cp39-abi3-macosx_11_0_arm64.whl:

Publisher: publish.yml on shenxianpeng/gitoxide

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file gitoxide-0.4.0-cp39-abi3-macosx_10_12_x86_64.whl.

File metadata

File hashes

Hashes for gitoxide-0.4.0-cp39-abi3-macosx_10_12_x86_64.whl
Algorithm Hash digest
SHA256 b644d455cced0e6862efc4da1a0119dfc3b85495e50661600f40523f6e05f727
MD5 ec6385285319d833fb81636a9413e462
BLAKE2b-256 f796b6b01a70ccd3cf4cad02ca370a8815ea06811c21a532deebfd01bb8d05ef

See more details on using hashes here.

Provenance

The following attestation bundles were made for gitoxide-0.4.0-cp39-abi3-macosx_10_12_x86_64.whl:

Publisher: publish.yml on shenxianpeng/gitoxide

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Release history Release notifications | RSS feed

This release

0.4.0 This release

6 files

0.2.0

6 files

0.1.0

6 files

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page