Every task that touches the filesystem starts with a path, and pathlib turns that path into an object that you can ask questions of, instead of a string that you have to cut up by hand. A Path knows its own parent folder, its own extension, whether it exists on disk, and how to find the files next to it. It also joins its parts with the same slash on every operating system, which removes a whole class of bugs that only happen on Windows.
The previous lesson in this module covered "Writing Files: Text, Newlines and CSV", and the next lesson in this module is about "Exceptions: try, except, else, finally, raise".
You build one with Path("data"), and from that point on you have something better than a string. You join a child onto it with /, you ask it for .name or .suffix, you create the folder it lives in with .mkdir(parents=True, exist_ok=True), and you read or write it with .read_text() and .write_text(). There is no os.path.join with three different separator characters, there is no manual string surgery to find the extension, and there is no os.makedirs that fails because the folder already exists.
Why prefer pathlib over os.path?
os.path is a group of functions that take strings and return strings. pathlib is a class, and its instances model a path. The difference shows up as soon as you do more than one thing with a path. With os.path you call os.path.dirname(p), then os.path.basename(p), then os.path.splitext(p), and you reassemble the pieces yourself. With Path the object carries those pieces with it.
| Task | os.path | pathlib |
|---|---|---|
| join two segments | os.path.join(a, b) | a / b |
| parent folder | os.path.dirname(p) | p.parent |
| file name | os.path.basename(p) | p.name |
| extension | os.path.splitext(p)[1] | p.suffix |
| does it exist | os.path.exists(p) | p.exists() |
| read text | open(p).read() | p.read_text() |
The path object is also a better citizen than a plain string. You can pass a Path straight to open(), to os.stat(), or to the functions in shutil without converting it back to a string first. The object also stays immutable, because every "modify" operation returns a new Path instead of changing the original one.
How do you build a path and inspect its parts?
A Path gives you its components as attributes. .name is the final component, .stem is that name without its last suffix, .suffix is the last suffix including the dot, and .parent is the folder that contains it. .parts gives you the whole thing as a tuple, and .suffixes lists every suffix, which is what you want for a name like archive.tar.gz.
from pathlib import Path
config = Path('settings') / 'app.toml'
report = Path('reports') / '2026' / 'q1.csv'
print('name :', config.name)
print('stem :', config.stem)
print('suffix:', config.suffix)
print('parent:', config.parent)
print('parts :', config.parts)
print('suffixes of archive.tar.gz:', Path('archive.tar.gz').suffixes)
The / operator is the joining syntax, and it works even when the part on the right looks like an absolute path. In that case the right-hand side wins, which is occasionally surprising, so build paths from small pieces that you trust instead of from text that a user typed.
How do you create a directory tree that may already exist?
mkdir() with no arguments creates exactly one folder, and it raises FileExistsError if that folder is already there. Two keyword arguments make it safe to repeat, which is exactly what you want in a script. parents=True creates the missing folders in between as well, and exist_ok=True stops the error when the target already exists.
from pathlib import Path
import tempfile
with tempfile.TemporaryDirectory() as tmp:
target = Path(tmp) / 'data' / 'raw' / '2026'
target.mkdir(parents=True, exist_ok=True)
print('created:', target.exists())
target.mkdir(parents=True, exist_ok=True)
print('running the same command twice is fine')
note = target / 'note.txt'
note.write_text('hello', encoding='utf-8')
print('contents:', note.read_text(encoding='utf-8'))
Creating a folder in a way that is safe to repeat is the difference between a script that you can run twice and a script that fails the second time. Anything that a setup script or a deploy script does should be safe to run again.
How do you list files by pattern?
Three methods cover most needs, and the difference between them is how deep they search. iterdir() gives you the immediate children of a folder and nothing more. glob(pattern) walks that folder and matches the names against a shell-style pattern, without going deeper by default. rglob(pattern) does the same thing but also recurses into every subfolder.
These patterns are not full regular expressions. * matches any run of characters inside a single path component, ? matches exactly one character, and ** spans folders.
from pathlib import Path
import tempfile
with tempfile.TemporaryDirectory() as tmp:
root = Path(tmp)
(root / 'src').mkdir()
(root / 'src' / 'main.py').write_text("print('hi')", encoding='utf-8')
(root / 'src' / 'util.py').write_text('x = 1', encoding='utf-8')
(root / 'docs').mkdir()
(root / 'docs' / 'readme.md').write_text('# hi', encoding='utf-8')
top_level = []
for path in root.iterdir():
top_level.append(path.name)
print('top level:', sorted(top_level))
one_level = []
for path in root.glob('src/*.py'):
one_level.append(path.name)
print('one level deep:', sorted(one_level))
every_py = []
for path in root.rglob('*.py'):
every_py.append(str(path.relative_to(root)))
print('every .py anywhere:', sorted(every_py))
Two practical notes here. Always sort() the results if you are going to print them or compare them, because the order that comes back from the filesystem is not guaranteed and it changes between machines and even between runs. And remember that glob and rglob return generators, so they produce their results lazily. Put them inside list() or sorted() when you want to use the results more than once.
How do you rename, move and delete paths?
Path offers the file operations that you would otherwise reach for os and shutil to get. .rename(target) moves or renames a file, .replace(target) does the same thing but overwrites the destination on Windows, .unlink() deletes a file, and .unlink(missing_ok=True) does not complain if the file is already gone. .touch() creates an empty file if it does not exist, and otherwise it updates the time that the file was last changed.
Two helpers that give you a new path are worth memorising. with_suffix(".json") returns a new path with the extension replaced, which is perfect for the "same file, different format" case. with_name("new.txt") swaps the final component and keeps the folder. Both of them return new objects, and neither of them ever changes the original path.
from pathlib import Path
import tempfile
with tempfile.TemporaryDirectory() as tmp:
root = Path(tmp)
original = root / 'notes.txt'
original.write_text('data', encoding='utf-8')
markdown = original.with_suffix('.md')
print('with_suffix:', markdown.name)
print('original untouched:', original.name)
renamed = original.with_name('renamed.txt')
print('with_name:', renamed.name, 'in', renamed.parent.name)
renamed.write_text('moved data', encoding='utf-8')
renamed.replace(original)
print('contents now:', original.read_text(encoding='utf-8'))
original.unlink(missing_ok=True)
original.unlink(missing_ok=True)
print('deleted twice with no error')
relative_to() is the odd one out, and it pays off quickly. Give it a parent path and it hands you back the child part of the path. It raises ValueError if the path is not really inside that parent, and that makes it a clean way to turn an absolute path back into a relative one for display.
What to remember
- Build paths with
Path(...)and join them with/. Never glue path pieces together withos.sep. - Ask the object for what you need:
.name,.stem,.suffix,.parent, and.parts. mkdir(parents=True, exist_ok=True)makes creating a folder safe to repeat.- Use
iterdir()for one level,glob()for a pattern, andrglob()for a recursive search. Sort the output. with_suffix()andwith_name()return new paths, which is exactly why they are safe to use inside an expression.
Try it yourself: inventory a folder of files
Pick a folder on your machine that has a mix of file types in it. Write a script that walks it with rglob and prints, for each file, its name, its extension, its size in kilobytes, and its parent folder. Sort the results so that the output stays the same between runs.
Then add a second stage. For every .txt file that you find, work out a new path with with_suffix(".md") and print it, but do not rename anything yet. Finally, make the script safe to run twice by giving the destination folder the same mkdir(parents=True, exist_ok=True) treatment that you would use in production.