`binascii`

The Python binascii module provides low-level C functions for converting between raw binary data and several ASCII-encoded binary representations. It is typically used internally by higher-level modules like base64 rather than called directly by application code.

Here is a quick example using the most common pair of functions:

>>> import binascii
>>> binascii.hexlify(b"\xb9\x01\xef")
b"b901ef"
>>> binascii.unhexlify(b"b901ef")
b"\xb9\x01\xef"

Each byte is represented as two hexadecimal digits, and unhexlify() reverses the conversion exactly.

Key Features

Converts binary data to hexadecimal strings and back with hexlify() and unhexlify()
Encodes and decodes base64 data with b2a_base64() and a2b_base64()
Encodes and decodes quoted-printable (MIME) data with b2a_qp() and a2b_qp()
Encodes and decodes UU-encoded data with b2a_uu() and a2b_uu()
Computes CRC-32 checksums compatible with ZIP files via crc32()
Implements all conversion functions in C for performance
Raises binascii.Error for invalid input and binascii.Incomplete for partial data

Frequently Used Functions

Object	Type	Description
`binascii.hexlify()`	Function	Converts bytes to their hex representation (alias: `b2a_hex()`)
`binascii.unhexlify()`	Function	Converts a hex string back to bytes (alias: `a2b_hex()`)
`binascii.b2a_base64()`	Function	Encodes bytes as a base64 ASCII line
`binascii.a2b_base64()`	Function	Decodes a base64 string back to bytes
`binascii.b2a_qp()`	Function	Encodes binary data as a quoted-printable string
`binascii.a2b_qp()`	Function	Decodes a quoted-printable string back to bytes
`binascii.b2a_uu()`	Function	Encodes binary data as a UU-encoded ASCII line
`binascii.a2b_uu()`	Function	Decodes a UU-encoded line back to bytes
`binascii.crc32()`	Function	Computes an unsigned 32-bit CRC checksum
`binascii.Error`	Exception	Signals a conversion error for malformed input
`binascii.Incomplete`	Exception	Signals incomplete input data rather than malformed input

Examples

Using hexlify() with an optional separator to format output:

>>> binascii.hexlify(b"\xb9\x01\xef", "-")
b"b9-01-ef"
>>> binascii.hexlify(b"\xb9\x01\xef", b"_", 2)
b"b9_01ef"

Encoding and decoding base64:

>>> binascii.b2a_base64(b"hello world")
b"aGVsbG8gd29ybGQ=\n"
>>> binascii.a2b_base64(b"aGVsbG8gd29ybGQ=\n")
b"hello world"

Computing a CRC-32 checksum incrementally:

>>> crc = binascii.crc32(b"hello")
>>> crc = binascii.crc32(b" world", crc)
>>> format(crc, "#010x")
"0x0d4a1185"

Common Use Cases

The most common tasks for binascii include:

Displaying raw bytes as readable hex strings for debugging or logging
Validating or computing checksums for file transfers and data integrity checks
Encoding binary data as base64 for transmission over text-based protocols
Supporting legacy formats such as UU-encoding and quoted-printable MIME data
Serving as the low-level backend for higher-level encoding modules

Real-World Example

The following example computes a CRC-32 checksum for a file in chunks, which is memory-efficient for large files:

import binascii

def file_crc32(path, chunk_size=65536):
    crc = 0
    with open(path, "rb") as f:
        for chunk in iter(lambda: f.read(chunk_size), b""):
            crc = binascii.crc32(chunk, crc)
    return format(crc, "#010x")

print(file_crc32("document.pdf"))

Each call to crc32() passes the previous result as the starting value, allowing the checksum to be built up incrementally without loading the entire file into memory.

Tutorial

Bytes Objects: Handling Binary Data in Python

In this tutorial, you'll learn about Python's bytes objects, which help you process low-level binary data. You'll explore how to create and manipulate byte sequences in Python and how to convert between bytes and strings. Additionally, you'll practice this knowledge by coding a few fun examples.

intermediate python

For additional information on related topics, take a look at the following resources: