os.strerror

strerror asks the C library, so the text is platform-dependent: the common codes read the same on Linux and Windows, but 0 is 'Success' on Linux and 'No error' on Windows, and unknown codes differ too. os.error IS OSError (the same class object), kept for old code; available everywhere.

os functionPython 3 (all)
Common call
os.strerror(errno.ENOENT)
Returns
'No such file or directory'
Replaces
Hard-coded error message tables
Watch out
Compare e.errno with errno.* constants, never the message text
os.strerror(codecode — An errno number (errno.ENOENT, e.errno ...). Positional only; a non-int raises TypeError.type: int · required, /)
→ str

Parameters

NameTypeRequiredDescription
codeintyesAn errno number (errno.ENOENT, e.errno ...). Positional only; a non-int raises TypeError.

Return value

str — The message for that error number, e.g. 'No such file or directory' for 2.

Common patterns

Raise a proper OSError subclass
With errno as the first argument OSError picks the matching subclass and formats the message.
import errno
import os
raise OSError(errno.ENOENT, os.strerror(errno.ENOENT), path)
Branch on the error number
Stable across platforms and locales, unlike the message.
import errno
try:
    os.rmdir(path)
except OSError as e:
    if e.errno != errno.ENOTEMPTY:
        raise
Message for an exit status or C return code
When a tool reports a bare errno number.
import os
print(f'failed: {os.strerror(code)} (errno {code})')

Examples

1. os.error is OSError
import os os.error is OSError
Returns
True
2. Message for ENOENT
import errno import os os.strerror(errno.ENOENT)
Returns
'No such file or directory'
3. A few common codes
import errno import os [os.strerror(c) for c in (errno.EACCES, errno.EEXIST, errno.ENOTDIR)]
Returns
['Permission denied', 'File exists', 'Not a directory']
4. Number to name
import errno errno.errorcode[2]
Returns
'ENOENT'
5. Building a full OSError
import errno import os e = OSError(errno.ENOENT, os.strerror(errno.ENOENT), 'cfg.ini') (type(e).__name__, str(e))
Returns
('FileNotFoundError', "[Errno 2] No such file or directory: 'cfg.ini'")
6. except os.error still works
import os try: open('missing.txt') except os.error as e: result = type(e).__name__ result
Returns
'FileNotFoundError'
7. The code must be an int
import os os.strerror('2')
Returns
TypeError: 'str' object cannot be interpreted as an integer

Pitfalls

1. OSError with only a message
A single argument keeps errno None and the class plain OSError, so callers cannot catch FileNotFoundError. Pass the errno first.
message only
e = OSError('No such file or directory: cfg.ini')
(type(e).__name__, e.errno)
('OSError', None)
errno, strerror
import errno
import os
e = OSError(errno.ENOENT, os.strerror(errno.ENOENT), 'cfg.ini')
(type(e).__name__, e.errno)
('FileNotFoundError', 2)
2. Passing the exception instead of its errno
strerror wants the number. The exception already carries its message in e.strerror.
strerror(e)
import os
try:
    open('missing.txt')
except OSError as e:
    os.strerror(e)
TypeError: 'FileNotFoundError' object cannot be interpreted as an integer
strerror(e.errno)
import os
try:
    open('missing.txt')
except OSError as e:
    msg = os.strerror(e.errno)
msg
'No such file or directory'

When to use

Use it
  • Formatting messages for raw errno values from C extensions, ctypes or exit codes
  • Raising OSError subclasses yourself with the standard message
Reach for something else
  • Deciding what happened → compare e.errno with errno.* or catch the subclass (FileNotFoundError ...)
  • New code: os.error → write OSError
  • Windows API error codes (WinError) → they are not errno values; e.winerror and e.strerror already hold the message

Notes

CPython impl
os.strerror calls the C strerror(); the docs say ValueError is raised on platforms where it returns NULL for an unknown code. os.error = OSError, the same object (os.error is OSError)
Platforms
Verified identical on Linux CPython 3.12 and Windows CPython 3.13 for errno 1, 2, 13, 17, 20, 21, 22, 28. Different: 0 ('Success' vs 'No error'), and unknown codes such as 9999 ('Unknown error 9999' vs 'Unknown error')
History
Since Python 3.3 IOError, EnvironmentError, socket.error, select.error and os.error are all aliases of OSError (PEP 3151)

FAQ

strerror asks the C library, and some messages differ between platforms (errno 0 is 'Success' on Linux but 'No error' on Windows). The examples only use codes whose text is the same on Linux and Windows.