Python os.fsdecode() Method

Python os.fsdecode() method is used to decode a path-like filename from a byte object into a string. It is essentially the counterpart to os.fsencode().




filename: This is a bytes object (containing encoded data) or a string.

Return value

It returns a decoded string from a bytes object.

Visual representation

Visual representation of python os.fsdecode() method

Example 1: Decoding a Byte object

import os

# Assume we have a byte string representing a file name
# Represents 'файл.txt' in byte object
filename_bytes = b'\xd1\x84\xd0\xb0\xd0\xb9\xd0\xbb.txt'

# Decode the filename
filename_str = os.fsdecode(filename_bytes)

print("Decoded Filename:", filename_str)


Decoded Filename: файл.txt

Example 2: Handling already decoded string

import os

# A regular string (already decoded)
filename_str = 'data.txt'

# Decode the filename
decoded_filename = os.fsdecode(filename_str)

print("Decoded Filename:", decoded_filename)


Decoded Filename: data.txt

Example 3: ‘surrogateescape’ error handler

The ‘surrogateescape’ error handler is used to deal with encoding and decoding errors, especially in situations where you’re working with file system data.

This handler will replace any bytes that cannot be encoded/decoded with a special Unicode surrogate character.

Later, when you encode/decode this string back to the original encoding, these surrogate characters will be converted to the original bytes.

import os

# A byte string with an invalid byte sequence for UTF-8
# Let's say the byte '\xff' does not represent a valid character in UTF-8
invalid_byte_str = b'file\xffname.txt'

# Normally, decoding this would raise a UnicodeDecodeError
# But with surrogateescape, it replaces the invalid byte with a Unicode surrogate
decoded_str = os.fsdecode(invalid_byte_str)

print("Decoded with surrogateescape:", decoded_str)


Decoded with surrogateescape: file�name.txt

In this decoded string, the invalid byte \xff is represented by a Unicode surrogate character. This surrogate character is not intended for normal use in text but serves as a placeholder for the invalid byte.

Re-encoding the String

The real utility of ‘surrogateescape’ becomes evident when you re-encode this string back to bytes:

re_encoded_byte_str = os.fsencode(decoded_str)

print("Re-encoded byte string:", re_encoded_byte_str)


Re-encoded byte string: b'file\xffname.txt'

That’s it!

Leave a Comment

This site uses Akismet to reduce spam. Learn how your comment data is processed.