base64.encode / decode

The file-to-file interface behind python -m base64. Both arguments are binary file objects (open(..., "rb") / "wb", or io.BytesIO); nothing is returned.

base64 functionPython 3.0+Live demo
Common call
base64.encode(open('in.bin', 'rb'), open('out.b64', 'wb'))
Returns
None — the result is in the output file
Replaces
Reading a whole file into memory just to Base64 it
Watch out
Text-mode files fail; decode checks padding line by line
base64.encode(inputinput — Readable binary file object: encode calls read(57) on it, decode calls readline().type: binary file · required, outputoutput — Writable binary file object; receives bytes.type: binary file · required)
→ None

Demo

Live evaluation
Encode text (as UTF-8) from one BytesIO into another and read the output buffer.
Try:
Inputs
textstrany text
Code
import base64, io
out = io.BytesIO()
base64.encode(io.BytesIO('hello world'.encode()), out)
out.getvalue()
Result
b'aGVsbG8gd29ybGQ=\n'

encode reads 57 bytes at a time and writes each chunk as one 76-character line plus a newline, so even short input ends in b"\n" and empty input writes nothing. decode runs a2b_base64 on every line separately: a 4-character group split across two lines is "Incorrect padding", and when line 2 fails, line 1 has already been written to the output.

Parameters

NameTypeRequiredDescription
inputbinary fileyesReadable binary file object: encode calls read(57) on it, decode calls readline().
outputbinary fileyesWritable binary file object; receives bytes.

Return value

None — Both write to output and return None.

Common patterns

Encode a file
Both files in binary mode; memory use stays small even for huge files.
import base64
with open('photo.jpg', 'rb') as src, open('photo.b64', 'wb') as dst:
    base64.encode(src, dst)
Decode a file
The input must be line-based Base64 (as produced by encode or encodebytes).
import base64
with open('photo.b64', 'rb') as src, open('photo.jpg', 'wb') as dst:
    base64.decode(src, dst)
From the shell
The module script calls these two functions.
# shell:
# python -m base64 photo.jpg > photo.b64
# python -m base64 -d photo.b64 > photo.jpg

Examples

1. Encode into a buffer
import base64, io out = io.BytesIO() base64.encode(io.BytesIO(b'hi'), out) out.getvalue()
Returns
b'aGk=\n'
2. Decode from a buffer
import base64, io out = io.BytesIO() base64.decode(io.BytesIO(b'aGVs\nbG8=\n'), out) out.getvalue()
Returns
b'hello'
3. Returns None
import base64, io base64.encode(io.BytesIO(b'hi'), io.BytesIO()) is None
Returns
True
4. Needs file objects
import base64, io base64.encode(b'hi', io.BytesIO())
Returns
AttributeError: 'bytes' object has no attribute 'read'
5. A real file
import base64 with open('data.bin', 'wb') as f: f.write(bytes(range(5))) with open('data.bin', 'rb') as src, open('data.b64', 'wb') as dst: base64.encode(src, dst) open('data.b64', 'rb').read()
Returns
b'AAECAwQ=\n'

Pitfalls

1. Opening files in text mode
encode needs bytes from read(); a text-mode file gives str.
open('rb') missing
import base64, io
base64.encode(io.StringIO('hi'), io.BytesIO())
TypeError: a bytes-like object is required, not 'str'
binary input
import base64, io
out = io.BytesIO()
base64.encode(io.BytesIO('hi'.encode()), out)
out.getvalue()
b'aGk=\n'
2. Hard-wrapped Base64 that splits groups
decode decodes line by line, so each line must hold whole 4-character groups. b64decode on the full text skips the newlines instead.
base64.decode
import base64, io
base64.decode(io.BytesIO(b'aGVsbG\n8='), io.BytesIO())
binascii.Error: Incorrect padding
b64decode(all)
import base64
base64.b64decode(b'aGVsbG\n8=')
b'hello'

When to use

Use it
  • Large files: both functions stream in small chunks
  • Producing or consuming the format of python -m base64 and MIME bodies
Reach for something else
  • Data already in memory → b64encode / encodebytes
  • Base64 text wrapped at arbitrary positions → b64decode on the whole text

Notes

CPython impl
encode: read(57) in a loop (topping up short reads), binascii.b2a_base64 per chunk. decode: for every readline(), binascii.a2b_base64(line)
Lines
MAXLINESIZE = 76 characters, MAXBINSIZE = 57 bytes per line

FAQ

For small files: base64.b64encode(open(path, 'rb').read()). For large ones stream it: with open(src, 'rb') as i, open(dst, 'wb') as o: base64.encode(i, o) — the output is in 76-character lines.