Tutorials Guides Reference Articles Cookbooks About

os module 

import os
Added in v1.0 · Updated March 13, 2026 · Modules
stdlib filesystem processes environment system

The os module is one of Python’s most fundamental standard library modules. It provides a portable interface for interacting with the operating system, allowing you to work with files and directories, manage processes, access environment variables, and gather system information. Whether you’re building command-line tools, servers, or scripts that need to work across different operating systems, os gives you the low-level system access you need while maintaining cross-platform compatibility.

The module abstracts away platform-specific differences, so the same Python code can work on Linux, macOS, and Windows. Functions like os.path.join() handle path separators correctly on each platform, and os.stat() returns consistent stat information regardless of the underlying filesystem.

Working with Directories

os.getcwd()

Returns the current working directory as a string. This is where relative file paths resolve from.

import os

cwd = os.getcwd()
print(f"Current directory: {cwd}")

Returns: str — The absolute path of the current working directory.

os.chdir(path)

Change the current working directory to the specified path.

import os

os.chdir('/tmp')
print(f"Changed to: {os.getcwd()}")

Parameters:

ParameterTypeDescription
pathstrThe directory path to change to

os.listdir(path=’.’)

Return a list of entries in the given directory. Each entry is a string (just the name, not the full path).

import os

for entry in os.listdir('.'):
    print(entry)

Parameters:

ParameterTypeDefaultDescription
pathstr'.'Directory to list

Returns: list[str] — List of file and directory names.

os.mkdir(path, mode=0o777, *, dir_fd=None)

Create a directory at the specified path with the given permission mode.

import os

os.mkdir('new_directory', mode=0o755)

Parameters:

ParameterTypeDefaultDescription
pathstr—Directory path to create
modeint0o777Permission mode (modified by umask)
dir_fdintNoneDirectory file descriptor (Unix only)

os.makedirs(name, mode=0o777, exist_ok=False)

Create a directory and any necessary parent directories. Unlike mkdir(), this function creates all intermediate directories in the path.

import os

os.makedirs('project/src/utils', mode=0o755, exist_ok=True)
print("Directories created")

Parameters:

ParameterTypeDefaultDescription
namestr—Directory path to create (including parents)
modeint0o777Permission mode
exist_okboolFalseIf True, don’t raise error if directory exists

os.rmdir(path)

Remove an empty directory.

import os

os.rmdir('empty_directory')

os.removedirs(path)

Remove directories recursively. This removes the specified directory and any empty parent directories up to the root.

import os

os.removedirs('project/src/utils')

File Operations

os.remove(path)

Remove (delete) a file. Cannot be used to remove directories.

import os

os.remove('temp.txt')

os.rename(src, dst, *, src_dir_fd=None, dst_dir_fd=None)

Rename a file or directory from src to dst.

import os

os.rename('old_name.txt', 'new_name.txt')

Parameters:

ParameterTypeDescription
srcstrSource path
dststrDestination path
src_dir_fdintSource directory file descriptor (optional)
dst_dir_fdintDestination directory file descriptor (optional)

os.renames(old, new)

Rename a file or directory recursively, creating any parent directories that don’t exist.

import os

os.renames('old_project/src/main.py', 'new_project/lib/main.py')

os.replace(src, dst)

Replace a file or directory atomically. Works even if the destination exists and on some platforms can atomically replace files.

import os

os.replace('config.new', 'config.txt')

os.stat(path, *, dir_fd=None, follow_symlinks=True)

Get status information about a file or directory. Returns a stat result object containing file size, timestamps, permissions, and more.

import os

st = os.stat('example.txt')
print(f"Size: {st.st_size} bytes")
print(f"Modified: {st.st_mtime}")
print(f"Permissions: {oct(st.st_mode)}")

Parameters:

ParameterTypeDefaultDescription
pathstr—File or directory path
dir_fdintNoneDirectory file descriptor
follow_symlinksboolTrueFollow symbolic links

Returns: os.stat_result — Object with attributes: st_mode, st_ino, st_dev, st_nlink, st_uid, st_gid, st_size, st_atime, st_mtime, st_ctime.

os.walk(top, topdown=True, onerror=None, followlinks=False, *, dir_fd=None)

Generate a 3-tuple for each directory in the tree, walking the tree top-down or bottom-up.

import os

for dirpath, dirnames, filenames in os.walk('project'):
    print(f"Directory: {dirpath}")
    print(f"  Subdirs: {dirnames}")
    print(f"  Files: {filenames}")

Yields: tuple[str, list[str], list[str]] — (dirpath, dirnames, filenames)

Environment Variables

os.environ

A dictionary-like object containing the process environment variables. Both keys and values are strings.

import os

# Read an environment variable
home = os.environ.get('HOME')
print(f"Home: {home}")

# Set an environment variable
os.environ['MY_APP_CONFIG'] = 'production'

# Delete an environment variable
del os.environ['TEMP_VAR']

os.getenv(key, default=None)

Get an environment variable value, returning a default if the variable doesn’t exist.

import os

debug = os.getenv('DEBUG', 'false')
api_key = os.getenv('API_KEY', '')

Parameters:

ParameterTypeDefaultDescription
keystr—Environment variable name
defaultanyNoneValue to return if variable doesn’t exist

Returns: str — The environment variable value or default.

os.putenv(key, value, /)

Set an environment variable. Note: prefer modifying os.environ directly as it automatically calls putenv().

import os

os.putenv('DATABASE_URL', 'postgres://localhost/mydb')
# Equivalent and preferred:
os.environ['DATABASE_URL'] = 'postgres://localhost/mydb'

os.get_exec_path(env=None)

Returns the list of directories searched for executables (the PATH environment variable).

import os

path_dirs = os.get_exec_path()
print("Executable search path:")
for p in path_dirs:
    print(f"  {p}")

Process Management

os.getpid()

Return the current process ID.

import os

print(f"Process ID: {os.getpid()}")

os.getppid()

Return the parent process ID.

import os

print(f"Parent process ID: {os.getppid()}")

os.system(command)

Execute a command in a subshell. Returns the exit code of the command.

import os

exit_code = os.system('echo "Hello from shell"')
print(f"Exit code: {exit_code}")

os.popen(command, mode=‘r’, buffering=-1)

Open a pipe to or from a command. Returns a file object connected to the pipe.

import os

output = os.popen('ls -la').read()
print(output)

os.kill(pid, sig)

Send a signal to a process. Useful for inter-process communication on Unix.

import os
import signal

# Send SIGTERM to terminate a process
os.kill(pid, signal.SIGTERM)

Path Manipulation

os.path.join(*paths)

Join one or more path components intelligently. Uses the correct separator for the platform.

import os

path = os.path.join('home', 'user', 'projects', 'app')
print(path)  # 'home/user/projects/app' on Unix

os.path.exists(path)

Return True if the path points to an existing file or directory.

import os

if os.path.exists('config.txt'):
    print("Config file exists")

os.path.isfile(path)

Return True if the path is an existing regular file.

os.path.isdir(path)

Return True if the path is an existing directory.

os.path.basename(path)

Return the base name of the file or directory path (the final component).

import os

print(os.basename('/home/user/document.txt'))  # 'document.txt'

os.path.dirname(path)

Return the directory name of the path (everything except the final component).

import os

print(os.dirname('/home/user/document.txt'))  # '/home/user'

os.path.splitext(path)

Split the path into a pair (root, ext) where ext is empty or starts with a dot.

import os

root, ext = os.path.splitext('document.txt')
print(f"Root: {root}, Extension: {ext}")  # Root: document, Extension: .txt

Examples

Walking a directory tree and finding files

import os

def find_files(directory, extension):
    """Find all files with a given extension."""
    matches = []
    for dirpath, dirnames, filenames in os.walk(directory):
        for filename in filenames:
            if filename.endswith(extension):
                matches.append(os.path.join(dirpath, filename))
    return matches

# Find all Python files in the current directory
py_files = find_files('.', '.py')
for f in py_files:
    print(f)

Output:

./main.py
./utils/helpers.py
./tests/test_main.py

Safely creating a directory structure

import os

def setup_project_structure(base_path):
    """Create a complete project directory structure."""
    structure = [
        'src',
        'src/utils',
        'src/models',
        'tests',
        'tests/unit',
        'tests/integration',
        'docs',
        'config',
    ]
    
    for dir_path in structure:
        full_path = os.path.join(base_path, dir_path)
        os.makedirs(full_path, exist_ok=True)
        print(f"Created: {full_path}")

# Usage
setup_project_structure('my_project')

Output:

Created: my_project/src
Created: my_project/src/utils
Created: my_project/src/models
Created: my_project/tests
Created: my_project/tests/unit
Created: my_project/tests/integration
Created: my_project/docs
Created: my_project/config

Common Patterns

Check before creating/removing

import os

# Check if file exists before removing
if os.path.exists('file.txt'):
    os.remove('file.txt')

# Check if directory exists before creating
if not os.path.exists('output'):
    os.makedirs('output')

Build paths cross-platform

import os

# Always use os.path.join for portability
config_path = os.path.join(os.environ['HOME'], '.config', 'myapp', 'settings.json')

Get file size and modification time

import os
from datetime import datetime

def file_info(path):
    st = os.stat(path)
    return {
        'size': st.st_size,
        'modified': datetime.fromtimestamp(st.st_mtime),
        'created': datetime.fromtimestamp(st.st_ctime),
    }

info = file_info('example.txt')
print(f"Size: {info['size']} bytes")
print(f"Modified: {info['modified']}")

Iterate over files with filtering

import os

# Get all .txt files in current directory
txt_files = [f for f in os.listdir('.') if f.endswith('.txt')]
print(txt_files)

See Also