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.
| Argument | Default | Effect |
|---|---|---|
url | False | URL-safe alphabet (- and _). |
pad | True | Add = padding. |
wrap | 0 | Insert \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"
| Key | Meaning |
|---|---|
valid | True exactly when decode would succeed. |
variant | standard, url, mixed or either; None when invalid. |
padded | The cleaned length, = included, is a multiple of 4; None when invalid. |
bytes | Decoded size; None when invalid. |
error | The 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