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

Documentation

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

Supported translations

Install

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

Install from local source

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.

Build from a local source

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

Run Tests

pip install pytest
pytest

Usage

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

Examples

• 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"
  

Options

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
  

Changelog

You can find all the change information here.

Contributing

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

Guidelines for contributing can be found here.

Disclaimer

Please read our disclaimer here.