Installation¶

Requirements¶

Python 3.8 or later
Jinja2 (auto-installed)
pylogshield (auto-installed)
Typer + Rich (auto-installed)

Install from PyPI¶

Bash

pip install badgeshield

Upgrade to the latest release:

Bash

pip install --upgrade badgeshield

Optional: Image support¶

Logo embedding and color tinting require Pillow. Install it with the image extra:

Bash

pip install "badgeshield[image]"

Without Pillow, badges are still generated correctly — logos are embedded as-is (no tinting) and text widths fall back to a character-width estimator.

Development install¶

Clone the repository and install in editable mode with test dependencies:

Bash

git clone https://github.com/vertex-ai-automations/badgeshield.git
cd badgeshield
pip install -e ".[dev]"          # runtime + pytest suite
pip install -e ".[dev,image]"    # also add Pillow for accurate text sizing

To work on the documentation:

Bash

pip install -e ".[docs]"         # zensical + mkdocstrings
zensical serve                   # preview at localhost:8000

Verify the installation¶

Bash

python -c "import badgeshield; print(badgeshield.__version__)"
badgeshield --help

You should see the version number and the CLI help text.

Virtual environments

Always install into a virtual environment (python -m venv .venv) to avoid dependency conflicts.