Skip to main content

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. A str is encoded as UTF-8 first.
  • decode(text: str | bytes) -> bytes raises base64hub.Base64Error, a subclass of ValueError, for the first problem from the left. Its position attribute is the 0-based position in the cleaned input; for a bad character or a misplaced =, char is that character.
  • validate(text) -> dict never raises. Valid input gives {"valid": True, "variant": ..., "padded": ..., "bytes": ...}: variant is standard (+ or / seen), url (- or _), mixed (both) or either (neither); padded means the length with = is a multiple of 4; bytes is the decoded length. Invalid input gives {"valid": False, "error": "<message decode would raise>"}.
  • data_uri(data, mime=None) -> str uses 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.

  1. Skip leading whitespace. If the input starts with data: (any case) and contains ;base64, (lower case), drop everything up to and including ;base64,.
  2. Remove every space, tab, CR and LF.
  3. Strip up to two trailing =; more, or = anywhere else, is an error.
  4. Accept both alphabets; any other character is an error with its position.
  5. 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 4
  • unexpected '=' at position 2: padding is only allowed at the end
  • too much padding: 3 '=' at position 2, at most 2 are allowed
  • invalid length: 5 characters leave a single character in the last group

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)

Source distribution for base64hub 1.0.0
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)

Table of built distributions (wheels) for base64hub 1.0.0
File Interpreter ABI Platform Actions
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 log

Release 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 log

Security 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.

Select from 2 files

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 log

A 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.

Release history Release notifications | RSS feed

This release

1.0.0 This release

2 release files Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page