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

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())

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).

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.

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, and blob reads.
  • Not wrapped yet: diff & status, tree listing, writing commits and the index, blame, 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 Jul 27, 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:
Newer release available (0.4.0)

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 Jul 27, 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.2.0.tar.gz (28.5 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.2.0-cp39-abi3-win_amd64.whl (1.6 MB view details)

Uploaded CPython 3.9+Windows x86-64

gitoxide-0.2.0-cp39-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (1.7 MB view details)

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

gitoxide-0.2.0-cp39-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl (1.7 MB view details)

Uploaded CPython 3.9+manylinux: glibc 2.17+ ARM64

gitoxide-0.2.0-cp39-abi3-macosx_11_0_arm64.whl (1.5 MB view details)

Uploaded CPython 3.9+macOS 11.0+ ARM64

gitoxide-0.2.0-cp39-abi3-macosx_10_12_x86_64.whl (1.6 MB view details)

Uploaded CPython 3.9+macOS 10.12+ x86-64

File details

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

File metadata

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

File hashes

Hashes for gitoxide-0.2.0.tar.gz
Algorithm Hash digest
SHA256 09378a64a7a4a636d35968272abae4e4b54e114cfe98c8b4f3561cd7e6453484
MD5 acac4fe674d8b55fe3dff37115c8990f
BLAKE2b-256 901ec623aea157ac7e03597cba6061e1114f5a8a407e0578505c8b8e36917b1a

See more details on using hashes here.

Provenance

The following attestation bundles were made for gitoxide-0.2.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.2.0-cp39-abi3-win_amd64.whl.

File metadata

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

File hashes

Hashes for gitoxide-0.2.0-cp39-abi3-win_amd64.whl
Algorithm Hash digest
SHA256 45255e73b8e07368f5e2bd3065512cfc61397cbafa46ad9df9896e232e022554
MD5 c1b3ec1c02002ac730196f59359c6c85
BLAKE2b-256 a8d4b6c3713e658fb155199ed5b403117489e1127f7833a849569f5ceb5300b5

See more details on using hashes here.

Provenance

The following attestation bundles were made for gitoxide-0.2.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.2.0-cp39-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl.

File metadata

File hashes

Hashes for gitoxide-0.2.0-cp39-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm Hash digest
SHA256 2991df04510a19cac482373491a1a63bc656ff4d8cb4eef974fb3d85f1159eb0
MD5 d1a032ce10f84f3161df47fdd8b7e4f2
BLAKE2b-256 9462b64bec1d57e1a23995fe4766959624c99cec4aa202b2702437b766d67336

See more details on using hashes here.

Provenance

The following attestation bundles were made for gitoxide-0.2.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.2.0-cp39-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl.

File metadata

File hashes

Hashes for gitoxide-0.2.0-cp39-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
Algorithm Hash digest
SHA256 53b0048ac45482d48ee241cf13d0a35c0267fea6a3cf6a652bfb7a8b5dd92ecf
MD5 6b616d41db30c01c3fd01fb1bc03a9d9
BLAKE2b-256 26ebe231f9eebd0c818e3b8b64aca845600136fcffbc2bcfbcd88defca7b2919

See more details on using hashes here.

Provenance

The following attestation bundles were made for gitoxide-0.2.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.2.0-cp39-abi3-macosx_11_0_arm64.whl.

File metadata

File hashes

Hashes for gitoxide-0.2.0-cp39-abi3-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 b23790268aa4744c0657bf2ad77c067aab70e6738eafd52eb22c39bc968f768c
MD5 529ddfa0af3a4612eed71dc9b6b588f9
BLAKE2b-256 c921c95852babc8e19ea9fc6ea9202911eecd1cd5b479a86b326097ced326207

See more details on using hashes here.

Provenance

The following attestation bundles were made for gitoxide-0.2.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.2.0-cp39-abi3-macosx_10_12_x86_64.whl.

File metadata

File hashes

Hashes for gitoxide-0.2.0-cp39-abi3-macosx_10_12_x86_64.whl
Algorithm Hash digest
SHA256 8773d68cd175d2b02d74a88bcdd3ac886ef96580f2b986fd606a6baf1adbb4e5
MD5 be0e88e6d866ab6e37883243edbd6b4a
BLAKE2b-256 4128cd93d018fcd5be660e09ef908ca32117eb9cc701b53266194d2818939c1e

See more details on using hashes here.

Provenance

The following attestation bundles were made for gitoxide-0.2.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

0.4.0

6 files

This release

0.2.0 This release

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