Installation¶

This page covers all supported installation methods for gitversioned.

Requirements¶

Before installing, ensure your system meets the following prerequisites:

Build Setup (Core Workflow)¶

gitversioned is primarily used as a build plugin. The preferred pathway is to configure it in your pyproject.toml utilizing Hatchling or Setuptools.

```toml
[build-system]
requires = ["hatchling", "gitversioned"]
build-backend = "hatchling.build"

[tool.hatch.version]
source = "gitversioned"
```

```toml
[build-system]
requires = ["setuptools>=61.0", "gitversioned"]
build-backend = "setuptools.build_meta"

[project]
dynamic = ["version"]
```

Standard Installation¶

If you need to install the package directly into an environment (e.g., for local development or testing without a build system), use pip or uv:

```bash
pip install gitversioned
```

```bash
uv pip install gitversioned
```

Verify the Installation¶

After installation, you can confirm it is available in your Python environment by running:

python -c "import gitversioned; print(gitversioned.__version__)"

You should see output similar to:

0.1.0

Install from Source¶

To install the latest unreleased code directly from the repository and set up a local development environment:

git clone https://github.com/markurtz/git-versioned.git
cd git-versioned

# Sync the development environment (installs all groups and extras)
uv sync --all-groups --all-extras

# Or, optionally install specific groups/extras:
uv sync --group dev --extra some_extra

[!TIP] This is the recommended setup for contributors looking to make changes to the source code.

Docker Installation¶

A pre-built Docker image is available for containerized environments:

# Pull the latest image
docker pull ghcr.io/markurtz/git-versioned:latest

# Run a one-off command
docker run --rm ghcr.io/markurtz/git-versioned:latest python -c "import gitversioned; print(gitversioned.__version__)"

For a persistent, volume-mounted setup using Docker Compose, see the docker-compose.yml in the root of the repository.

Platform-Specific Notes¶

Python, `pip`, and `uv` work seamlessly on macOS. We recommend using `brew install uv` to get started.

Use your distribution's package manager to install Python 3.10+ (e.g., `sudo apt install python3`).

Ensure Python is added to your PATH during the Windows installer setup.

Upgrading¶

To upgrade an existing installation to the latest release:

```bash
pip install --upgrade gitversioned
```

```bash
uv pip install --upgrade gitversioned
```

Uninstalling¶

```bash
pip uninstall gitversioned
```

```bash
uv pip uninstall gitversioned
```

Troubleshooting¶

If you continue to experience issues, please visit our Support page.

Next: Quick Start →