The os Module - Navigating Directories

diagram os.walk hands you a list you are meant to edit mermaid

  flowchart TD
  A["os.walk('.')"] --> B["yield (root, dirs, files)"]
  B --> C["your loop body runs"]
  C --> D{"did you modify dirs IN PLACE?"}
  D -->|"dirs.remove('b')"| E["that subtree is never visited"]
  D -->|"dirs = [...] -- rebinding"| F["no effect; the walker still has the old list"]
  D -->|no| G["descend into every subdirectory"]
  E --> H["next root"]
  G --> H
  H --> B
  I["topdown=False"] --> J["children first -- pruning no longer works"]

Each step yields the current directory, its subdirectories and its files. The subdirectory list is not just information -- with the default top-down walk, os.walk reads it again after your loop body to decide where to go next. Removing an entry from it in place is how you skip a whole subtree, which is the difference between a script that finishes and one that walks into node_modules.

Pruning works, but only in place and only top-down

Verified on a tree of top.txt, a/1.txt, a/b/2.txt, a/b/c/3.txt:

python

for root, dirs, files in os.walk("."):
    if "b" in dirs:
        dirs.remove("b")     # in place

The walk visited . and ./a, then stopped — a/b and a/b/c were never entered.

Two conditions, and both matter:

It has to be in place. dirs.remove(...), dirs[:] = [...] or del dirs[i] all work. Writing dirs = [d for d in dirs if ...] rebinds a local name, the walker keeps its own list, and the filter silently does nothing.

It only works with topdown=True, the default. With topdown=False the children have already been walked by the time you see the list, so editing it changes nothing.

This is the standard way to skip .git, node_modules or __pycache__, and it is much faster than walking them and discarding the results.

What os is for

The os module provides:

• current working directory
• directory listing
• environment variables
• basic path manipulation (but prefer pathlib for paths)

Current working directory

cwd.py

import os
 
print(os.getcwd())

List files

listdir.py

import os
 
for name in os.listdir("."):
    print(name)

Change directory

chdir.py

import os
 
os.chdir("/tmp")
print(os.getcwd())

Environment variables

env_vars.py

import os
 
print(os.environ.get("HOME"))

Notes

For paths, use pathlib.Path whenever possible.

🧪 Try It Yourself

Exercise 1 – List Files with os.listdir

pch.exerciseTag pch.exerciseTitle

Exercise 2 – Join Paths with os.path.join

pch.exerciseTag pch.exerciseTitle

Exercise 3 – Write and Read a File

pch.exerciseTag pch.exerciseTitle