Python os.fsencode() Method

The os.fsencode() function encodes a file path with ‘surrogateescape’ error handler or to bytes if the filename is already of type bytes.

The encoding used is determined by sys.getfilesystemencoding().

When dealing with file systems that expect bytes objects for filenames rather than the usual str (string) type, this function is helpful.




filename: It is a file path to encode. Can be a string or a bytes object.

Return value

If filename is of type str (string), it is encoded using the filesystem encoding and the ‘surrogateescape’ error handler.

If the filename is already a bytes object, it is returned as is.

Visual representation

Visual representation of os.fsencode() function in Python

Example 1: Basic usage

import os

filename_str = "data.txt"

# Check the type before encoding
print("Before encoding:", type(filename_str))

# Encoding the filename
filename_encoded = os.fsencode(filename_str)

# Check the type after encoding
print("After encoding:", type(filename_encoded))


Before encoding: <class 'str'>

After encoding: <class 'bytes'>

This function is designed to help bridge the gap between Python’s string handling and the byte-oriented file system, ensuring better compatibility, especially in environments with non-ASCII filenames.

Example 2: Handling Non-ASCII Filenames

import os

# A filename with non-ASCII characters
filename = "файл.txt" # 'file.txt' in Russian

# Encoding the filename
encoded_filename = os.fsencode(filename)

print("Original:", filename)
print("Encoded:", encoded_filename)


Original: файл.txt

Encoded: b'\xd1\x84\xd0\xb0\xd0\xb9\xd0\xbb.txt'

That’s it!

Leave a Comment

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