bible-translations

A Python package and CLI for fetching Bible translations on demand. This project does not bundle or redistribute any Bible text — it fetches publicly available, public-domain 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

Only public-domain translations are supported; see the disclaimer.

Install

You can Install from PyPI

pip install bible-translations 

The package provides a CLI command:

bt
# or
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.