pybase64

library1.5.0pypypi✓ verified 27d ago

pybase64 is a Python library that provides a fast Base64 encoding/decoding implementation by wrapping the highly optimized `libbase64` C library. It maintains an active development status with regular updates to support new Python versions and performance enhancements. The current version is 1.4.3, and new releases often coincide with Python's release cycle.

serialization

pip install pybase64

github ↗package ↗docs ↗

INSTALL

IMPORT

SIG · PYBASE64

pybase64

serializationpythonv1.5.0

Install

1.7s avg

Import

—

Disk

16MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v1.5.0 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

py 3.10–3.95 runs

installs and imports cleanly · install 0.0s · import 0.000s · 18.1MB

glibc

py 3.10–3.95 runs

installs and imports cleanly · install 1.7s · import 0.000s · 19MB

16MB installed

● package 16MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

pybase64

✓ import pybase64

b64encode

✓ pybase64.b64encode

b64decode

✓ pybase64.b64decode

standard_b64encode

✓ pybase64.standard_b64encode

urlsafe_b64encode

✓ pybase64.urlsafe_b64encode

This quickstart demonstrates basic Base64 encoding and decoding using `pybase64`. It shows both standard and URL-safe operations. For optimal decoding performance, especially with trusted input, using `validate=True` with `b64decode` is recommended.

import pybase64 original_data = b'Hello, world! This is a test string for pybase64.' # Standard Base64 encoding encoded_standard = pybase64.standard_b64encode(original_data) print(f"Standard Encoded: {encoded_standard}") # Standard Base64 decoding decoded_standard = pybase64.standard_b64decode(encoded_standard) print(f"Standard Decoded: {decoded_standard}\n") # URL-safe Base64 encoding encoded_urlsafe = pybase64.urlsafe_b64encode(original_data) print(f"URL-safe Encoded: {encoded_urlsafe}") # URL-safe Base64 decoding with validation for best performance decoded_urlsafe = pybase64.urlsafe_b64decode(encoded_urlsafe, validate=True) print(f"URL-safe Decoded: {decoded_urlsafe}") assert original_data == decoded_standard assert original_data == decoded_urlsafe

Debug

Known issues

breakingpybase64 dropped support for Python 3.6 and 3.7 with the release of version 1.4.0. Users on these Python versions must either upgrade their Python environment or remain on pybase64 versions prior to 1.4.0.

fix

Upgrade to Python 3.8 or newer, or pin pybase64 version to <1.4.0.

affects: <1.4.0 (for old Python versions)

gotchaFor the fastest decoding, especially with trusted input, it is recommended to use the `b64decode` function with the `validate=True` argument. This avoids character validation overhead.

fix

Call `pybase64.b64decode(encoded_bytes, validate=True)`

affects: All versions

gotchaPrior to version 1.3.2, `pybase64` might have produced incorrect outcomes when decoding non C-contiguous buffers, particularly in PyPy environments. This was fixed in v1.3.2.

fix

Upgrade to pybase64 version 1.3.2 or later.

affects: <1.3.2

deprecatedA deprecation warning related to `argparse.FileType` usage was fixed in version 1.4.2. If you use `pybase64` within command-line tools that rely on `argparse.FileType`, older versions might emit warnings.

fix

Upgrade to pybase64 version 1.4.2 or later.

affects: <1.4.2

gotchaUnlike some legacy `base64` module functions, `pybase64`'s core `b64encode` and `b64decode` functions primarily work with and return `bytes` objects. If string or bytearray output is required, use `b64encode_as_string` (returns `str`) or `b64decode_as_bytearray` (returns `bytearray`) introduced in v1.1.0.

fix

Convert `bytes` manually using `.decode('ascii')` or `.encode('ascii')`, or use `b64encode_as_string` / `b64decode_as_bytearray` for specific return types.

affects: All versions

gotcha`pybase64.urlsafe_b64decode` does not support the `validate` keyword argument. This argument is specific to `pybase64.b64decode` for optimizing performance by skipping character validation.

fix

Remove the `validate` argument when calling `pybase64.urlsafe_b64decode`.

affects: All versions

Errors

Common errors & fixes

ModuleNotFoundError: No module named 'pybase64'

The `pybase64` library has not been installed in your Python environment or is not accessible within your current Python path.

fix

Install the library using pip: `pip install pybase64`

binascii.Error: Incorrect padding

This error occurs during Base64 decoding when the input string's length is not a multiple of 4, or it contains invalid characters, indicating that the data is corrupted, incomplete, or not properly padded.

fix

Ensure the Base64 string is correctly padded (its length must be a multiple of 4, often by adding '=' characters at the end) and free of non-Base64 characters. You might need to add padding manually if it's missing: `s += '=' * (-len(s) % 4)` before decoding.

UnicodeDecodeError: 'utf-8' codec can't decode byte 0x__ in position __: invalid start byte

This error typically happens when you try to decode the `bytes` output of `pybase64.b64decode()` into a `str` using an incorrect text encoding (e.g., 'utf-8') for the original data. Base64 encoding operates on binary data, and its decoded output is also binary (`bytes`), not necessarily a UTF-8 string.

fix

Do not attempt to decode the result of `pybase64.b64decode()` into a string unless you are certain of its original text encoding. If the original data was indeed a string with a specific encoding (e.g., 'latin-1' or 'cp1252'), use that encoding for decoding: `decoded_bytes.decode('latin-1')`. If the data is truly binary, keep it as `bytes`.

ERROR: Could not find a version that satisfies the requirement base64

Users often encounter this when attempting to install the `pybase64` library by incorrectly typing `pip install base64`. The `base64` module is part of Python's standard library and does not need to be installed via pip, hence no package named 'base64' exists on PyPI.

fix

To install the `pybase64` library, use the correct package name: `pip install pybase64`

Upgrade

Version history

1.5.0latest on PyPI · released Aug 8, 2026

Audit

Dependencies

No dependency data recorded yet.

Agent activity

13 hits · last 30 days

node

Resources

githubhttps://github.com/mayeut/pybase64 ↗

packagehttps://pypi.org/project/pybase64/ ↗

docshttps://pybase64.readthedocs.io/en/stable ↗