Skip to content
Tutorials Center
My learning

Topics

Python Reference · String Methods

Python str.encode() method

Reference for Python str.encode(): turn a string into bytes with an encoding, choose an error handler, and handle UnicodeEncodeError correctly.

The str.encode() method converts a string, which is a sequence of Unicode characters, into a bytes object using a character encoding. You need bytes whenever text leaves your program: writing to a binary file, sending over a network or hashing.

The default encoding is UTF-8, which can represent every Unicode character. Other encodings, such as ASCII or Latin-1, can only represent some characters and need an error strategy for the rest. The reverse operation is bytes.decode().

Python
data = "héllo".encode("utf-8")
print(data)            # b'h\xc3\xa9llo'

Try it

Python Strings to bytes and back

Press Run (or Ctrl + Enter) to see the result here.

Program input · what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Python Error handlers

Press Run (or Ctrl + Enter) to see the result here.

Program input · what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Syntax

Python
str.encode(encoding="utf-8", errors="strict")
Name Description
encoding Optional. The name of the codec, such as "utf-8", "ascii", "latin-1" or "utf-16". Default "utf-8".
errors Optional. What to do with characters the codec cannot represent. Default "strict".

Common error handlers:

Handler Effect
"strict" Raise UnicodeEncodeError.
"ignore" Drop the character.
"replace" Substitute ?.
"xmlcharrefreplace" Insert an XML entity such as ☕.
"backslashreplace" Insert an escape such as ☕.

Return value: a bytes object.

Raises: UnicodeEncodeError (a subclass of ValueError) for unencodable characters with the strict handler; LookupError for an unknown encoding name.

Usage notes

  • Characters versus bytes. One character may take 1 to 4 bytes in UTF-8, so len(text) and len(text.encode()) can differ. Use the byte length for sizes on disk or on the wire.
  • Always be explicit when files or protocols are involved. Relying on a platform default causes bugs when code moves to another machine. UTF-8 is the right default almost everywhere.
  • ignore and replace lose data. Use them for display or logging, never for data you must restore.
  • Lone surrogates (such as "\ud800") cannot be encoded as UTF-8 with the strict handler. The "surrogateescape" handler exists for round-tripping undecodable bytes.
  • Byte order. "utf-16" adds a byte order mark; "utf-16-le" and "utf-16-be" do not.
  • Immutable result. Use bytearray() if you need to modify the data after encoding.
  • Opposite direction. bytes.decode() or str(data, "utf-8"). Decoding with the wrong codec gives garbled text or an error.