base64hub
Base64 encode, decode and validate from Python or the shell. One small package, standard library only,
with a b64 command that behaves the same as the base64hub CLI for Go and npm.
- Lenient decoding: standard and URL-safe alphabets (even mixed), missing padding, spaces, tabs
and line breaks,
data:...;base64,prefixes. Errors name the problem and its position. - Encoding options: URL-safe alphabet (RFC 4648 §5), no padding, line wrapping (76 for MIME), data URIs with the MIME type sniffed from the bytes (PNG, JPEG, GIF, WebP, PDF, SVG, text).
- Validation that tells you the variant, whether it is padded and how many bytes it holds.
- Python 3.9 or newer, zero dependencies, type hints included.
Home page: base64hub.com/pypi · Docs: base64hub.com/docs/python · Online tools: base64hub.com
Install
As a command-line tool (isolated environment, puts b64 on your PATH):
pipx install base64hub
As a library:
pip install base64hub
Command line
b64 [flags] [TEXT]
With TEXT, b64 works on its UTF-8 bytes; without it, it reads stdin (or -i FILE).
$ b64 "Hello, hub!"
SGVsbG8sIGh1YiE=
$ b64 -d SGVsbG8sIGh1YiE=
Hello, hub!
$ printf '\xfb\xff\xbf' | b64 --url
-_-_
$ b64 --url --no-pad "Привет"
0J_RgNC40LLQtdGC
| Flag | Meaning |
|---|---|
-d, --decode |
decode (writes the raw bytes, nothing appended) |
-u, --url |
URL-safe alphabet, - and _ (encode) |
-n, --no-pad |
no = padding (encode) |
-w N, --wrap N |
wrap encoded output every N characters; 0 = no wrap, 76 = MIME |
--data-uri |
output data:<mime>;base64,... (encode) |
-m TYPE, --mime TYPE |
MIME type for --data-uri (default: sniffed) |
--validate |
print valid (<variant>, <bytes> bytes), or invalid: <reason> and exit 1 |
-i FILE, --input FILE |
read FILE instead of stdin (- = stdin) |
-o FILE, --output FILE |
write FILE instead of stdout (- = stdout) |
-h, --help |
help |
-v, --version |
print b64 <version> |
More examples:
$ b64 -w 76 -i photo.jpg -o photo.b64
$ b64 -d -i photo.b64 -o photo.jpg
$ b64 --data-uri -i logo.png
data:image/png;base64,iVBORw0KGgo...
$ b64 --validate "SGVsbG8sIGh1YiE"
valid (either, 11 bytes)
$ b64 -d -- -_-_ | xxd -p
fbffbf
Flags may come before or after TEXT. Short flags can't be combined (-d -n, not -dn) and take
their value as the next argument (-w 76, not -w76); long flags also accept --wrap=76. Use --
before TEXT that starts with -, which URL-safe Base64 often does. A bare - as TEXT means stdin.
These are usage errors: encoding flags (-u, -n, -w, --data-uri, -m) with -d or
--validate; -u, -n or -w with --data-uri (data URIs are standard padded Base64 on one line);
--mime without --data-uri; TEXT together with -i; the same file for -i and -o.
Errors go to stderr as b64: <message>. Exit codes: 0 success, 1 invalid input or I/O error,
2 usage error. When a run fails, a file written with -o is removed, so no partial output is left.
b64 behaves exactly like the Go build of the command, the reference implementation.
The package installs the same command under a second name, base64hub, and runs as
python -m base64hub too.
Library
from base64hub import encode, decode, validate, data_uri
encode("Hello, hub!") # 'SGVsbG8sIGh1YiE='
encode(b"\xfb\xff\xbf", url=True) # '-_-_'
encode("Привет", url=True, pad=False) # '0J_RgNC40LLQtdGC'
encode(bytes(100), wrap=76) # MIME lines, no trailing newline
decode("SGVsbG8sIGh1YiE") # b'Hello, hub!' (padding optional)
decode("data:text/plain;base64,SGk=") # b'Hi'
decode("a+b_") # b'k\xe6\xff' (mixed alphabets)
validate("-_-_")
# {'valid': True, 'variant': 'url', 'padded': True, 'bytes': 3}
validate("Zm9v!")
# {'valid': False, 'error': "invalid character '!' at position 4"}
data_uri(b"hi") # 'data:text/plain;charset=utf-8;base64,aGk='
data_uri(png_bytes) # 'data:image/png;base64,...'
data_uri(svg_bytes, "image/svg+xml") # MIME given explicitly
encode(data: bytes | str, *, url=False, pad=True, wrap=0) -> str. Astris encoded as UTF-8 first.decode(text: str | bytes) -> bytesraisesbase64hub.Base64Error, a subclass ofValueError, for the first problem from the left. Itspositionattribute is the 0-based position in the cleaned input; for a bad character or a misplaced=,charis that character.validate(text) -> dictnever raises. Valid input gives{"valid": True, "variant": ..., "padded": ..., "bytes": ...}:variantisstandard(+or/seen),url(-or_),mixed(both) oreither(neither);paddedmeans the length with=is a multiple of 4;bytesis the decoded length. Invalid input gives{"valid": False, "error": "<message decode would raise>"}.data_uri(data, mime=None) -> struses the standard alphabet with padding and never wraps.sniff_mime(data)returns the type it would pick.
How decoding works
Whitespace means exactly space, tab, CR and LF; anything else, such as a no-break space, is an invalid character.
- Skip leading whitespace. If the input starts with
data:(any case) and contains;base64,(lower case), drop everything up to and including;base64,. - Remove every space, tab, CR and LF.
- Strip up to two trailing
=; more, or=anywhere else, is an error. - Accept both alphabets; any other character is an error with its position.
- A length that leaves one character over (length mod 4 = 1) is an error.
Errors are found left to right, positions count characters of the cleaned input from 0, and the messages are exactly:
invalid character '!' at position 4unexpected '=' at position 2: padding is only allowed at the endtoo much padding: 3 '=' at position 2, at most 2 are allowedinvalid length: 5 characters leave a single character in the last group
Links
- Package page: base64hub.com/pypi
- Documentation: base64hub.com/docs/python
- Base64 tools in the browser: base64hub.com
- Source and issues: github.com/base64hub-com/base64hub-python
License
MIT
Metadata
Release files for base64hub 1.0.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| base64hub-1.0.0.tar.gz | 21.9 kB | With provenance | Details for base64hub-1.0.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| base64hub-1.0.0-py3-none-any.whl | Python 3 | none | any | Details for base64hub-1.0.0-py3-none-any.whl |
Total release size: 36.0 kB
Release files / base64hub-1.0.0.tar.gz
| Download URL | base64hub-1.0.0.tar.gz |
|---|---|
| Size | 21.9 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
3e8c3ec2e395a118db3a533541b7236e0e385442212444c0d9bb79b0fd3ad4ee
|
|
BLAKE2b-256 checksum How to use checksums |
94029b689ea852f80fcc03460024c903969863036f29d5925612ebdf5757b58d
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 21, 2026.
Transparency logRelease files / base64hub-1.0.0-py3-none-any.whl
| Download URL | base64hub-1.0.0-py3-none-any.whl |
|---|---|
| Size | 14.1 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
9caa7fd38ce5a9cf9abd0d20b6954de1d725195a862bc72c9034b35ec1cf5ace
|
|
BLAKE2b-256 checksum How to use checksums |
027b64b55e3fbe4b794ac7983c1982f0cbe5cb77560617fbc27b98b38e94cd6d
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 21, 2026.
Transparency logSecurity for base64hub 1.0.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for base64hub-1.0.0.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 21, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.