Upload a file
  1. base64hub
  2. Docs
  3. Python package

Python Package Reference

base64hub on PyPI is a standard-library-only module for Python 3.9 and later, with five functions, one exception and the b64 command.

Install

pip install base64hub      # library, inside a virtual environment
pipx install base64hub     # b64 command
from base64hub import encode, decode, validate, data_uri, sniff_mime, Base64Error

The package ships type hints (py.typed).

encode(data, *, url=False, pad=True, wrap=0)

Encodes bytes, or a str as UTF-8, and returns a str.

ArgumentDefaultEffect
urlFalseURL-safe alphabet (- and _).
padTrueAdd = padding.
wrap0Insert \n after every N characters, none at the end; 76 is MIME.
encode("Hello, hub!")                  # 'SGVsbG8sIGh1YiE='
encode("Привет", url=True, pad=False)  # '0J_RgNC40LLQtdGC'
encode(b"foobar", wrap=4)              # 'Zm9v\nYmFy'
encode(b"\xfb\xff\xbf")                # '+/+/'

decode(text)

Decodes Base64 to bytes. Spaces, tabs and line breaks, a data:...;base64, prefix, missing padding and both alphabets are accepted. Invalid input raises Base64Error, a subclass of ValueError; for a bad character, position and char say where and what.

decode("SGVsbG8sIGh1YiE")               # b'Hello, hub!'
decode("Zm9v YmFy")                     # b'foobar'
decode("data:text/plain;base64,SGk=")   # b'Hi'

try:
    decode("Zm9v!")
except Base64Error as e:
    print(e, e.position)                # invalid character '!' at position 4 4

Because Base64Error is a ValueError, existing except ValueError blocks keep working.

validate(text)

Checks text without raising and returns a dict with the same keys every time.

validate("-_-_")
# {'valid': True, 'variant': 'url', 'padded': True, 'bytes': 3, 'error': None}
validate("Zm9v!")["error"]
# "invalid character '!' at position 4"
KeyMeaning
validTrue exactly when decode would succeed.
variantstandard, url, mixed or either; None when invalid.
paddedThe cleaned length, = included, is a multiple of 4; None when invalid.
bytesDecoded size; None when invalid.
errorThe reason when invalid, otherwise None.

data_uri(data, mime=None) and sniff_mime(data)

data_uri builds a data:<mime>;base64,<payload> string, standard alphabet, padded, never wrapped. Without mime, sniff_mime picks the type: PNG, JPEG, GIF, WebP, PDF and SVG by signature, text/plain;charset=utf-8 for UTF-8 text, otherwise application/octet-stream.

data_uri(b"Hi")                         # 'data:text/plain;charset=utf-8;base64,SGk='
data_uri(b"a,b", mime="text/csv")       # 'data:text/csv;base64,YSxi'
sniff_mime(b"\x89PNG\r\n\x1a\n")        # 'image/png'

The b64 command

pipx install base64hub installs b64. Flags, messages and exit codes match the CLI reference. The Python build reads the whole input into memory before working on it; for very large files use the Go build.

Compared with the base64 module

The standard library rejects unpadded input (binascii.Error: Incorrect padding), silently drops characters outside the alphabet unless you pass validate=True, and needs a separate function for URL-safe input. base64hub accepts what is safe to accept and raises for the rest. More on the standard module in Base64 in Python.

Updated Nov 22, 2026