mayeut/pybase64: Fast Base64 encoding/decoding in Python

.. SETUP VARIABLES .. |license-status| image:: https://img.shields.io/badge/license-BSD%202--Clause-blue.svg :target: https://github.com/mayeut/pybase64/blob/master/LICENSE .. |pypi-status| image:: https://img.shields.io/pypi/v/pybase64.svg :target: https://pypi.python.org/pypi/pybase64 .. |python-versions| image:: https://img.shields.io/pypi/pyversions/pybase64.svg .. |rtd-status| image:: https://readthedocs.org/projects/pybase64/badge/?version=stable :target: http://pybase64.readthedocs.io/en/stable/?badge=stable :alt: Documentation Status .. |gha-status| image:: https://github.com/mayeut/pybase64/workflows/Build%20and%20upload%20to%20PyPI/badge.svg :target: https://github.com/mayeut/pybase64/actions?query=workflow%3A%22Build+and+upload+to+PyPI%22 .. |codecov-status| image:: https://codecov.io/gh/mayeut/pybase64/branch/master/graph/badge.svg :target: https://codecov.io/gh/mayeut/pybase64/branch/master .. END OF SETUP

Fast Base64 implementation ==========================

This project is a wrapper on libbase64 _.

It aims to provide a fast base64 implementation for base64 encoding/decoding.

Installation ============

.. code::

pip install pybase64

Usage =====

`pybase64 uses the same API as Python base64 "modern interface" (introduced in Python 2.4) for an easy integration.

To get the fastest decoding, it is recommended to use the pybase64.b64decode with validate=True (or ignorechars=b"") and padded=True when possible.


.. code:: python
import pybase64
print(pybase64.b64encode(b'>>>foo???', altchars='_:'))
    # b'Pj4_Zm9vPz8:'
    print(pybase64.b64decode(b'Pj4_Zm9vPz8:', altchars='_:', validate=True))
    # b'>>>foo???'
# Standard encoding helpers
    print(pybase64.standard_b64encode(b'>>>foo???'))
    # b'Pj4+Zm9vPz8/'
    print(pybase64.standard_b64decode(b'Pj4+Zm9vPz8/'))
    # b'>>>foo???'
# URL safe encoding helpers
    print(pybase64.urlsafe_b64encode(b'>>>foo???'))
    # b'Pj4-Zm9vPz8_'
    print(pybase64.urlsafe_b64decode(b'Pj4-Zm9vPz8_'))
    # b'>>>foo???'
.. begin cli
A command-line tool is also provided. It has encode, decode and benchmark subcommands.
.. code::
usage: pybase64 [-h] [-V] {benchmark,encode,decode} ...
pybase64 command-line tool.
positional arguments:
      {benchmark,encode,decode}
                            tool help
        benchmark           -h for usage
        encode              -h for usage
        decode              -h for usage
optional arguments:
      -h, --help            show this help message and exit
      -V, --version         show program's version number and exit
.. end cli

Full documentation on Read the Docs _.


Benchmark
=========
.. begin benchmark
Running Python 3.15.0rc1, Apple clang version 21.0.0 (clang-2100.1.1.101), macOS 26.5.2, Apple M1 Max
.. code::
pybase64 1.5.0 (C extension active - NEON)
    bench: altchars=None, validate=True, padded=True
    pybase64.encodebytes:     6595 MB/s (135,696 bytes -> 183,309 bytes)
    pybase64.b64encode:      17492 MB/s (135,696 bytes -> 180,928 bytes)
    pybase64.b64decode:       9037 MB/s (180,928 bytes -> 135,696 bytes)
    base64.encodebytes:       2386 MB/s (135,696 bytes -> 183,309 bytes)
    base64.b64encode:         2653 MB/s (135,696 bytes -> 180,928 bytes)
    base64.b64decode:         2656 MB/s (180,928 bytes -> 135,696 bytes)
    bench: altchars=None, validate=True, padded=False
    pybase64.b64encode:      17547 MB/s (135,696 bytes -> 180,928 bytes)
    pybase64.b64decode:       2521 MB/s (180,928 bytes -> 135,696 bytes)
    base64.b64encode:         2656 MB/s (135,696 bytes -> 180,928 bytes)
    base64.b64decode:         2655 MB/s (180,928 bytes -> 135,696 bytes)
    bench: altchars=None, ignorechars=b'', padded=False
    pybase64.b64decode:       2510 MB/s (180,928 bytes -> 135,696 bytes)
    base64.b64decode:         2655 MB/s (180,928 bytes -> 135,696 bytes)
    bench: altchars=None, ignorechars=b'\n', padded=True
    pybase64.b64decode:       2370 MB/s (183,308 bytes -> 135,696 bytes)
    base64.b64decode:         2087 MB/s (183,308 bytes -> 135,696 bytes)
    bench: altchars=None, ignorechars=b'\n', padded=False
    pybase64.b64decode:       2365 MB/s (183,308 bytes -> 135,696 bytes)
    base64.b64decode:         1964 MB/s (183,308 bytes -> 135,696 bytes)
    bench: altchars=None, validate=False, padded=True
    pybase64.b64decode:       2369 MB/s (183,308 bytes -> 135,696 bytes)
    base64.b64decode:         2030 MB/s (183,308 bytes -> 135,696 bytes)
    bench: altchars=None, validate=False, padded=False
    pybase64.b64decode:       2361 MB/s (183,308 bytes -> 135,696 bytes)
    base64.b64decode:         1982 MB/s (183,308 bytes -> 135,696 bytes)
    bench: altchars=b'-_', validate=True, padded=True
    pybase64.b64encode:      10900 MB/s (135,696 bytes -> 180,928 bytes)
    pybase64.b64decode:       5974 MB/s (180,928 bytes -> 135,696 bytes)
    base64.b64encode:         2675 MB/s (135,696 bytes -> 180,928 bytes)
    base64.b64decode:         1186 MB/s (180,928 bytes -> 135,696 bytes)
    bench: altchars=b'-_', validate=True, padded=False
    pybase64.b64encode:      10798 MB/s (135,696 bytes -> 180,928 bytes)
    pybase64.b64decode:       2135 MB/s (180,928 bytes -> 135,696 bytes)
    base64.b64encode:         2571 MB/s (135,696 bytes -> 180,928 bytes)
    base64.b64decode:         1154 MB/s (180,928 bytes -> 135,696 bytes)
    bench: altchars=b'-_', ignorechars=b'', padded=True
    pybase64.b64decode:       5770 MB/s (180,928 bytes -> 135,696 bytes)
    base64.b64decode:         2629 MB/s (180,928 bytes -> 135,696 bytes)
    bench: altchars=b'-_', ignorechars=b'', padded=False
    pybase64.b64decode:       2201 MB/s (180,928 bytes -> 135,696 bytes)
    base64.b64decode:         2606 MB/s (180,928 bytes -> 135,696 bytes)
    bench: altchars=b'-_', ignorechars=b'\n', padded=True
    pybase64.b64decode:       2058 MB/s (183,308 bytes -> 135,696 bytes)
    base64.b64decode:         2069 MB/s (183,308 bytes -> 135,696 bytes)
    bench: altchars=b'-_', ignorechars=b'\n', padded=False
    pybase64.b64decode:       2058 MB/s (183,308 bytes -> 135,696 bytes)
    base64.b64decode:         1882 MB/s (183,308 bytes -> 135,696 bytes)
    bench: altchars=b'-_', validate=False, padded=True
    pybase64.b64decode:       2030 MB/s (183,308 bytes -> 135,696 bytes)
    base64.b64decode:         1005 MB/s (183,308 bytes -> 135,696 bytes)
    bench: altchars=b'-_', validate=False, padded=False
    pybase64.b64decode:       2081 MB/s (183,308 bytes -> 135,696 bytes)
    base64.b64decode:         1031 MB/s (183,308 bytes -> 135,696 bytes)
.. end benchmark
.. begin changelog
Changelog
=========
1.5.0
------

Speed-up translation on aarch64
Fix invalid data successfully decoded when using altchars (slice ends with padding)
Fix thread safety selecting codec

Add padded and wrapcol parameters to b64encode

Add padded parameter to urlsafe_b64encode

Add padded parameter to b64decode & urlsafe_b64decode

urlsafe_b64decode now defaults to padded=False to align with Python 3.15 behavior

Add ignorechars and canonical parameters to b64decode


Handle excess padding with the same behavior as CPython 3.15

Reject non-ASCII strings in b64decode when validate=False

Deprecate accepting the + and / characters with an alternative alphabet when decoding

Use ValueError instead of AssertionError` on altchars length validation
Add SBOM to PyPI wheels
Publish python 3.15 wheels
Drop python 3.8 support
Stop publishing python 3.13t wheels

1.4.3 -----

Publish Android Python 3.14 wheels
Publish GraalPy v25 wheels

1.4.2 -----

Update base64 library (Windows ARM64 Neon support)
Publish Python 3.14 wheels
Publish Linux riscv64 wheels
Publish Android wheels
Publish iOS wheels
Publish GraalPy wheels

1.4.1 -----

Publish PyPy 3.11 wheels
Publish armv7l wheels

1.4.0 -----

Publish python 3.13 wheels
Add support for free-threaded builds
Add MSYS2 support for C-extension
Better logging on base64 build failure when C-extension build is optional
Drop python 3.6 & 3.7 support

1.3.2 -----

Update base64 library
PyPy: fix wrong outcome with non C-contiguous buffer

1.3.1 -----

Add missing py.typed marker

1.3.0 -----

Update base64 library
Add AVX512-VBMI implementation
Rework extension build to remove adherence on distutils
Publish python 3.12 wheels
Documentation now uses furo theme

1.2.3 -----

Update base64 library
Publish python 3.11 wheels

1.2.2 -----

Update base64 library
Fix C extension build on musl distros
Publish musllinux wheels

1.2.1 -----

Publish PyPy 3.8 (pypy38_pp73) wheels

1.2.0 -----

Release the GIL
Publish CPython 3.10 wheels
Drop python 3.5 support

1.1.4 -----

Add macOS arm64 wheel

1.1.3 -----

GitHub Actions: fix build on tag

1.1.2 -----

Add PyPy wheels
Add aarch64, ppc64le & s390x manylinux wheels

1.1.1 -----

Move CI from TravisCI/AppVeyor to GitHub Actions
Fix publication of Linux/macOS wheels

1.1.0 -----

Add b64encode_as_string, same as b64encode but returns a str object instead of a bytes object
Add b64decode_as_bytearray, same as b64decode but returns a bytarray object instead of a bytes object
Speed-Up decoding from UCS1 strings

1.0.2 -----

Update base64 library
Publish python 3.9 wheels

1.0.1 -----

Publish python 3.8 wheels

1.0.0 -----

Drop python 3.4 support
Drop python 2.7 support

0.5.0 -----

Publish python 3.7 wheels
Drop python 3.3 support

0.4.0 -----

Speed-up decoding when validate==False

0.3.1 -----

Fix deployment issues

0.3.0 -----

Add encodebytes function

0.2.1 -----

Fixed invalid results on Windows

0.2.0 -----

Added documentation
Added subcommands to the main script:

* help * version * encode * decode * benchmark

0.1.2 -----

Updated base64 native library

0.1.1 -----

Fixed deployment issues

0.1.0 -----

First public release

.. end changelog

mayeut/pybase64: Fast Base64 encoding/decoding in Python

Reading Mode

Related Stories

Supabase Is Acquiring Turso

A 20-year-long permanent cookie: America.gov and tracking

Mozilla shutting down Solo AI website creator

AI Makes Me Sad

Big Tech ruined the cloud, so we're renaming ours

Related Stories