Install
pip install base64hub # the library, in a virtual environment
pipx install base64hub # the b64 command, isolated
Python 3.9 or later, nothing else. The package uses only the standard library, so installing it pulls in no other code.
Encode, decode, validate
Four functions, with the types you would expect in Python:
from base64hub import encode, decode, validate, data_uri
encode("Hello, hub!") # 'SGVsbG8sIGh1YiE='
encode("Привет", url=True, pad=False) # '0J_RgNC40LLQtdGC'
encode(b"foobar", wrap=4) # 'Zm9v\nYmFy'
decode("SGVsbG8sIGh1YiE") # b'Hello, hub!'
decode("data:text/plain;base64,SGk=") # b'Hi'
validate("+/+/")["variant"] # 'standard'
data_uri(b"Hi") # 'data:text/plain;charset=utf-8;base64,SGk='
encode takes str (encoded as UTF-8) or bytes and returns str. decode returns bytes and raises base64hub.Base64Error, a subclass of ValueError, for input that is not Base64. validate never raises: it returns a dict with valid, variant, padded, bytes and error, which holds the reason when the input is invalid and None otherwise.
base64hub vs the base64 module
The standard base64 module is correct and fast. It is also strict where people paste messy input and lax where it should complain. These are its real outputs on Python 3.13:
import base64
base64.b64decode("SGVsbG8sIGh1YiE") # binascii.Error: Incorrect padding
base64.b64decode("Zm9v!YmFy") # b'foobar', the "!" is dropped silently
base64.b64decode("-_-_") # b'', URL-safe characters are dropped
base64 module | base64hub | |
|---|---|---|
Missing = padding | Incorrect padding | accepted |
| URL-safe input | separate urlsafe_b64decode | accepted by decode |
| Invalid characters | dropped unless validate=True | ValueError |
| Return type of encode | bytes | str |
data: URIs | no | data_uri(), and stripped when decoding |
If you only encode your own data, the standard library is enough; Base64 in Python shows how. Reach for base64hub when input comes from users, logs, JSON or URLs and you want either a correct result or a clear error.
The b64 command
pipx install base64hub gives you the same b64 command as the native CLI:
$ b64 "Hello, hub!"
SGVsbG8sIGh1YiE=
$ b64 --url --no-pad "Привет"
0J_RgNC40LLQtdGC
The Python build reads input into memory before working on it; the Go build streams. Everything else, including flags and exit codes, is identical. The Python docs list every function and flag.
FAQ
How do I install a Base64 command line tool with Python?
pipx install base64hub puts the b64 command on your PATH in its own environment. pip install base64hub inside a virtual environment works too.
Why does base64.b64decode say Incorrect padding?
The standard library insists on a length that is a multiple of 4. base64hub.decode() adds the missing = itself, so decode("SGVsbG8sIGh1YiE") returns b'Hello, hub!'.
Which Python versions does base64hub support?
Python 3.9 and later. The package has no dependencies outside the standard library.
How do I decode URL-safe Base64 in Python without knowing the variant?
Call base64hub.decode(): it accepts the standard and the URL-safe alphabet in the same string. With the standard library you have to pick b64decode or urlsafe_b64decode yourself.