Python OS Module

The Story That Explains the OS Module

The os module is Python's bridge to your operating system. Anything involving files, folders, paths, or environment configuration ultimately touches os. Its centrepiece — os.walk() — is the tool of choice for recursively traversing directory trees, and the reason many one-line scripts can process thousands of files.

The Five Families of os Functions

The os module is huge, but every function falls into one of five families. Learn the shape of each family and you'll never guess which function to reach for.

Getting Oriented — Where Am I?

import os

# Where is my script running from?
print(os.getcwd())              # '/home/alice/projects/blog'

# What's in this folder?
print(os.listdir())              # ['posts', 'index.html', 'style.css']

# List a DIFFERENT folder without moving
print(os.listdir("/tmp"))         # files in /tmp

# Move into a folder (changes cwd for the whole process)
os.chdir("/tmp")
print(os.getcwd())              # '/tmp'

# Check if something exists (before touching it)
print(os.path.exists("data.csv"))       # True / False
print(os.path.isfile("data.csv"))       # True — is a file
print(os.path.isdir("reports"))        # True — is a directory

Creating & Removing Directories

import os

# Make ONE directory — fails if parent doesn't exist
os.mkdir("reports")

# Make a WHOLE CHAIN of directories in one call
os.makedirs("data/2025/january/raw")   # creates all four

# exist_ok=True — don't error if the folder already exists
os.makedirs("cache", exist_ok=True)

# Remove an EMPTY directory
os.rmdir("reports")              # fails if it has any content

# Remove a CHAIN of empty directories, bottom-up
os.removedirs("data/2025/january/raw")

# To remove a directory that ISN'T empty, use shutil
import shutil
shutil.rmtree("cache")             # nuclear option — no coming back

File Operations — Rename, Remove, Inspect

import os

# Rename or move a file (same call does both)
os.rename("draft.txt", "final.txt")
os.rename("final.txt", "archive/final.txt")  # cross-directory move

# Delete a file (permanent, no bin)
os.remove("temp.log")

# Get detailed metadata — size, timestamps, permissions
info = os.stat("main.py")
print(f"Size:     {info.st_size} bytes")
print(f"Modified: {info.st_mtime}")      # seconds since epoch
print(f"Mode:     {oct(info.st_mode)}")  # file permission bits

# Convert timestamp to a readable date
from datetime import datetime
modified = datetime.fromtimestamp(info.st_mtime)
print(f"Modified: {modified:%Y-%m-%d %H:%M}")

Path Anatomy — What Makes Up a Path

Every file path can be broken into named parts, and os.path has a function to extract each one. Understanding the anatomy makes the API self-evident.

import os

path = "/home/alice/data/report.csv"

print(os.path.basename(path))     # 'report.csv'
print(os.path.dirname(path))      # '/home/alice/data'

# Split in one call — returns (dirname, basename)
print(os.path.split(path))
# ('/home/alice/data', 'report.csv')

# Split off the extension — returns (root, ext)
print(os.path.splitext(path))
# ('/home/alice/data/report', '.csv')

# Build a path — os.path.join() uses the right separator per OS
new_path = os.path.join("/home/alice", "reports", "2026", "jan.csv")
print(new_path)
# '/home/alice/reports/2026/jan.csv'   (or backslashes on Windows)

# Absolute path from a relative one
print(os.path.abspath("data.csv"))

os.walk() — The Star of the Show

os.walk() recursively visits every subdirectory in a tree and yields three values for each folder it enters. Once you understand its yield shape, processing every file in a project becomes a five-line script.

The Yield Shape

import os

for dirpath, dirnames, filenames in os.walk("project"):
    print(dirpath)     # current folder (str)
    print(dirnames)    # sub-folders inside it (list of str)
    print(filenames)   # files inside it (list of str)

Visualising os.walk — Tree to Tuples

This is the diagram to burn into memory. On the left, a folder tree. On the right, what os.walk yields for each step, in order. The numbered dots show the traversal sequence — top-down, depth-first by default.

The Corresponding Code Output

import os

for dirpath, dirnames, filenames in os.walk("project"):
    print(f"Folder: {dirpath}")
    print(f"  Sub-folders: {dirnames}")
    print(f"  Files:       {filenames}")
    print()

Common os.walk Patterns

Pattern 1 — Full Paths of Every File

import os

for dirpath, _, filenames in os.walk("project"):
    for f in filenames:
        full_path = os.path.join(dirpath, f)
        print(full_path)

Pattern 2 — Only .py Files

import os

py_files = []
for dirpath, _, filenames in os.walk("project"):
    for f in filenames:
        if f.endswith(".py"):
            py_files.append(os.path.join(dirpath, f))

print(f"Found {len(py_files)} Python files")

Pattern 3 — Skip Folders In-Place

import os

# Modify dirnames IN PLACE to prune the walk
# This tells os.walk NOT to descend into those folders

skip = {".git", "__pycache__", "node_modules", ".venv"}

for dirpath, dirnames, filenames in os.walk("project"):
    # Remove skip-folders from dirnames — walk won't visit them
    dirnames[:] = [d for d in dirnames if d not in skip]

    for f in filenames:
        print(os.path.join(dirpath, f))

Pattern 4 — Bottom-Up Walk (For Deletion)

import os

# topdown=False visits the DEEPEST folders first
# Essential for cleanup — you can't rmdir a parent that still has children

for dirpath, dirnames, filenames in os.walk("temp_data", topdown=False):
    for f in filenames:
        os.remove(os.path.join(dirpath, f))
    os.rmdir(dirpath)                    # now empty, safe to remove

Environment Variables

Environment variables are how the shell passes configuration to your program. API keys, database URLs, debug flags, PATH — all of it. Reading them with os is one line.

import os

# Direct access — raises KeyError if missing
home = os.environ["HOME"]
user = os.environ["USER"]

# Safe access with a default
db_url = os.getenv("DATABASE_URL", "sqlite:///dev.db")
debug  = os.getenv("DEBUG", "0") == "1"

# Set an environment variable for THIS process
os.environ["MY_APP_MODE"] = "production"

# Loop over every env var
for key, value in os.environ.items():
    if key.startswith("APP_"):
        print(f"{key}={value}")

Process & System Info

import os

# Which OS is this? Useful for platform-specific branches
print(os.name)             # 'posix' on Linux/macOS, 'nt' on Windows

# Process info
print(os.getpid())          # current process ID
print(os.getppid())         # parent process ID

# Available CPUs — useful for parallel processing
print(os.cpu_count())       # e.g. 8

# Run a shell command (simple use only)
os.system("echo Hello from shell")

# For anything real, use subprocess — safer, captures output
import subprocess
result = subprocess.run(
    ["ls", "-la"], capture_output=True, text=True
)
print(result.stdout)

Practical Real-World Examples

Example 1 — Count Files By Extension

import os
from collections import Counter

counts = Counter()
for _, _, filenames in os.walk("project"):
    for f in filenames:
        ext = os.path.splitext(f)[1].lower() or "(no ext)"
        counts[ext] += 1

for ext, n in counts.most_common():
    print(f"{ext:10s} {n}")

Example 2 — Total Disk Usage of a Folder

import os

def folder_size(root):
    total = 0
    for dirpath, _, filenames in os.walk(root):
        for f in filenames:
            path = os.path.join(dirpath, f)
            try:
                total += os.path.getsize(path)
            except OSError:
                pass                     # broken symlink, permission denied
    return total

size = folder_size("project")
print(f"{size:,} bytes ({size / 1024 / 1024:.2f} MB)")

Example 3 — Rename Files In Bulk

import os

# Rename every .jpeg to .jpg in a photo folder
for dirpath, _, filenames in os.walk("photos"):
    for f in filenames:
        if f.endswith(".jpeg"):
            old = os.path.join(dirpath, f)
            new = os.path.join(dirpath, f[:-5] + ".jpg")
            os.rename(old, new)
            print(f"{old}  →  {new}")

Example 4 — Find Files Modified Today

import os
from datetime import datetime, timedelta

cutoff = (datetime.now() - timedelta(days=1)).timestamp()

recent = []
for dirpath, _, filenames in os.walk("logs"):
    for f in filenames:
        path = os.path.join(dirpath, f)
        if os.path.getmtime(path) > cutoff:
            recent.append(path)

print(f"{len(recent)} file(s) modified in the last 24 hours")

Example 5 — Find Duplicate Filenames Across a Tree

import os
from collections import defaultdict

seen = defaultdict(list)

for dirpath, _, filenames in os.walk("project"):
    for f in filenames:
        seen[f].append(os.path.join(dirpath, f))

# Filenames appearing in more than one location
duplicates = {name: paths for name, paths in seen.items() if len(paths) > 1}

for name, paths in duplicates.items():
    print(f"{name} appears in:")
    for p in paths:
        print(f"  {p}")

Modern Alternative — pathlib

Since Python 3.4, pathlib offers an object-oriented alternative to os.path. Same jobs, cleaner syntax. It doesn't fully replace os (there's no direct walk equivalent until 3.12's Path.walk()), but for path manipulation, pathlib is usually the better choice in new code.

from pathlib import Path

p = Path("/home/alice/data/report.csv")

print(p.name)      # 'report.csv'
print(p.stem)      # 'report'
print(p.suffix)    # '.csv'
print(p.parent)    # PosixPath('/home/alice/data')

# The / operator joins paths
new_p = Path("/home/alice") / "reports" / "2026" / "jan.csv"

# Glob for files — often simpler than os.walk
for py_file in Path("project").rglob("*.py"):
    print(py_file)

Quick Reference Table

Common Pitfalls

Golden Rules