bible-translations

A Python package (PyPI) and CLI for fetching Bible translations on demand. Fetches publicly available translations from BibleGateway at request time, either as Python objects (via the API) or as exported JSON files (via the CLI).

Full API and CLI reference: https://jadenzaleski.github.io/bible-translations/

Install the CLI with uv:

uv tool install bible-translations

Install with pip:

pip install bible-translations

Run:

bt
# or
bible-translations

If bt isn't found afterward, run uv tool update-shell and open a new terminal.

To use bible-translations as a library, add it to your own project instead:

uv add bible-translations

Clone the repo and install in editable mode:

git clone https://github.com/jadenzaleski/bible-translations.git
cd bible-translations
python -m venv .venv
source .venv/bin/activate
pip install --upgrade pip setuptools wheel
pip install -e ".[dev]"

The last command (pip install -e ".[dev]") automatically installs the package and any tools listed under [project.optional-dependencies].dev (e.g. pytest, ruff). The -e flag creates a "symlink" so changes you make to src/bible_translations/ are immediately available when importing the package.

Generate a wheel and source distribution:

python -m build

This creates a dist/ folder with:

• .whl → wheel (binary distribution)
• .tar.gz → source distribution

You can install the wheel to test locally:

pip install dist/bible_translations*.whl

pip install pytest
pytest

The package provides a CLI for fetching and exporting Bible translations.

• Fetch a verse:

  bt verse "John 3:16"

• Fetch a chapter:

  bt chapter "John 3"

• Fetch a book:

  bt book John

• Fetch all books:

  bt books

• Fetch a selection:

  bt selection "John 3:16" "John 3:18"

In any command, you can specify the translation, output filename, and format:

• Specify translation (default: KJV):

  bt verse "John 3:16" --translation KJV
  # or
  bt verse "John 3:16" -t KJV

• Specify output file and format (default: export, json):

  bt verse "John 3:16" my_export json

You can find all the change information here.

Be sure to check out the bible-translations project to see where you can help!

Guidelines for contributing can be found here.

Please read our disclaimer here.