`errno`

The Python errno module provides named integer constants for the error codes that the operating system uses to indicate why a system call failed, allowing Python programs to identify and handle specific error conditions.

Here’s a quick look at reading an error code from an OSError:

>>> import errno, os
>>> try:
...     os.remove("/nonexistent.txt")
... except OSError as e:
...     print(e.errno, errno.errorcode[e.errno])
...
2 ENOENT

Since Python 3.3, OSError automatically raises more specific subclasses such as FileNotFoundError and PermissionError for common errno values, so direct errno comparisons are mainly needed for less common error codes or when working with raw numeric codes from external sources.

Key Features

Exposes POSIX errno values as named integer constants (for example, errno.ENOENT == 2 on Linux)
Provides the errorcode dictionary to convert any numeric error code to its symbolic name
Works alongside os.strerror() to obtain human-readable error descriptions for any code
Available constants vary by platform; errno.errorcode.keys() lists all constants on the current system
Covers file system errors, socket errors, process errors, and I/O errors

Frequently Used Constants and Attributes

Object	Type	Description
`errno.ENOENT`	Constant	Indicates a missing file or directory; maps to `FileNotFoundError`
`errno.EACCES`	Constant	Flags denied access to a resource; maps to `PermissionError`
`errno.EPERM`	Constant	Signals an unpermitted operation; maps to `PermissionError`
`errno.EEXIST`	Constant	Reports that a file already exists; maps to `FileExistsError`
`errno.EISDIR`	Constant	Denotes that the path is a directory; maps to `IsADirectoryError`
`errno.ENOTEMPTY`	Constant	Flags a non-empty directory
`errno.EINVAL`	Constant	Indicates an invalid argument
`errno.EAGAIN`	Constant	Signals a temporarily unavailable resource; maps to `BlockingIOError`
`errno.ECONNREFUSED`	Constant	Reports a refused connection
`errno.ETIMEDOUT`	Constant	Denotes a timed-out connection; maps to `TimeoutError`
`errno.EPIPE`	Constant	Indicates a broken pipe; maps to `BrokenPipeError`
`errno.errorcode`	Dictionary	Maps numeric error codes to their symbolic names

Examples

Using errorcode to look up the symbolic name for a numeric error code:

>>> import errno

>>> errno.errorcode[2]
'ENOENT'
>>> errno.errorcode[13]
'EACCES'

Combining errno with os.strerror() to build a descriptive error message:

>>> import errno, os

>>> code = errno.ENOSPC
>>> f"Error {code}: {os.strerror(code)}"
'Error 28: No space left on device'

Checking for ENOTEMPTY, an error code that has no dedicated OSError subclass:

>>> import errno, os

>>> os.mkdir("/tmp/test_dir")
>>> open("/tmp/test_dir/file.txt", "w").close()
>>> try:
...     os.rmdir("/tmp/test_dir")
... except OSError as e:
...     if e.errno == errno.ENOTEMPTY:
...         print("Directory is not empty")
...
Directory is not empty

Common Use Cases

The most common tasks for errno include:

Checking OSError.errno when handling errors that have no dedicated OSError subclass
Converting raw numeric error codes to symbolic names using errorcode
Passing errno values to os.strerror() to produce human-readable error messages
Writing portable error-handling code that works consistently across Linux, macOS, and Windows

Real-World Example

The following script tries to create a directory and handles two specific errno conditions without raising for either:

import errno
import os

def safe_mkdir(path):
    try:
        os.mkdir(path)
        print(f"Created directory: {path}")
    except OSError as e:
        if e.errno == errno.EEXIST:
            print(f"Directory already exists: {path}")
        elif e.errno == errno.EACCES:
            print(f"Permission denied: {path}")
        else:
            raise

safe_mkdir("/tmp/my_app_data")
safe_mkdir("/tmp/my_app_data")

Run it:

$ python safe_mkdir.py
Created directory: /tmp/my_app_data
Directory already exists: /tmp/my_app_data

The second call does not raise because the code checks for EEXIST and treats it as a non-fatal condition. The bare raise in the else branch re-raises any unexpected OSError, ensuring that unhandled error codes are not silently swallowed.

Tutorial

Python Exceptions: An Introduction

In this beginner tutorial, you'll learn what exceptions are good for in Python. You'll see how to raise exceptions and how to handle them with try ... except blocks.

basics python

For additional information on related topics, take a look at the following resources: