Skip to main content
Editor

Python pathlib: Modern File Path Handling

Intermediate20 min5 exercises70 XP
0/5 exercises

Imagine navigating to a friend's house. You could follow vague paper directions like "turn left at the big tree, then right at the red mailbox." Or you could use GPS, which understands addresses, calculates routes, and handles all the tricky details for you.

Python's pathlib module is like GPS for file paths. The old way (os.path) treats paths as plain strings and requires you to manually juggle slashes, extensions, and platform differences. pathlib gives you smart Path objects that understand what paths are and how they work.

In this tutorial, you'll learn how to create, inspect, join, and search paths using pathlib. Since we're running in the browser, we'll focus on the path manipulation features that work without a real filesystem.

How Do You Create a Path Object?

Import PurePosixPath from pathlib and pass it a string. A PurePosixPath is a path object that works with Unix-style forward slashes and doesn't need a real filesystem.

Creating PurePosixPath objects
from pathlib import PurePosixPath
# Create path objects
home = PurePosixPath('/home/alice')
project = PurePosixPath('/home/alice/projects/myapp')
file = PurePosixPath('/home/alice/documents/report.pdf')
print(home)
print(project)
print(file)
Output
/home/alice
/home/alice/projects/myapp
/home/alice/documents/report.pdf

On your own computer, you'd normally use Path (which detects your operating system). Here we use PurePosixPath because it works everywhere, including in the browser. The methods and properties are the same.

What Can You Learn from a Path Object?

Path objects have useful properties that let you extract parts of a file path without any string splitting or slicing.

Extracting parts of a path
from pathlib import PurePosixPath
p = PurePosixPath('/home/alice/projects/app/main.py')
print(f'Full path: {p}')
print(f'Name: {p.name}') # main.py
print(f'Stem: {p.stem}') # main (without extension)
print(f'Suffix: {p.suffix}') # .py
print(f'Parent: {p.parent}') # /home/alice/projects/app
print(f'Parts: {p.parts}') # all pieces
Output
Full path:  /home/alice/projects/app/main.py
Name:       main.py
Stem:       main
Suffix:     .py
Parent:     /home/alice/projects/app
Parts:      ('/', 'home', 'alice', 'projects', 'app', 'main.py')

Let's break down what each property gives you:

  • name - The final file or folder name: main.py
  • stem - The name without the extension: main
  • suffix - The file extension including the dot: .py
  • parent - The directory containing this file: /home/alice/projects/app
  • parts - A tuple of every piece of the path
  • Handling files with multiple extensions
    from pathlib import PurePosixPath
    # Multiple extensions
    archive = PurePosixPath('/data/backup.tar.gz')
    print(f'Name: {archive.name}')
    print(f'Suffix: {archive.suffix}') # .gz (last extension)
    print(f'Suffixes: {archive.suffixes}') # ['.tar', '.gz'] (all)
    print(f'Stem: {archive.stem}') # backup.tar
    Output
    Name: backup.tar.gz
    Suffix: .gz
    Suffixes: ['.tar', '.gz']
    Stem: backup.tar

    Walking up the directory tree

    You can chain .parent to go up multiple levels, or use the .parents property to get all ancestor directories.

    Navigating up with .parent and .parents
    from pathlib import PurePosixPath
    p = PurePosixPath('/home/alice/projects/app/src/main.py')
    print(f'Parent: {p.parent}')
    print(f'Grandparent: {p.parent.parent}')
    print()
    print('All ancestors:')
    for ancestor in p.parents:
    print(f' {ancestor}')
    Output
    Parent: /home/alice/projects/app/src
    Grandparent: /home/alice/projects/app
    
    All ancestors:
      /home/alice/projects/app/src
      /home/alice/projects/app
      /home/alice/projects
      /home/alice
      /home
      /

    How Do You Join Paths Together?

    One of the best features of pathlib is the / operator for joining paths. Instead of worrying about slashes, you just use / between Path objects or strings.

    Joining paths with the / operator
    from pathlib import PurePosixPath
    base = PurePosixPath('/home/alice')
    # Join paths with /
    docs = base / 'documents'
    report = base / 'documents' / 'report.txt'
    project = base / 'projects' / 'myapp' / 'main.py'
    print(docs)
    print(report)
    print(project)
    Output
    /home/alice/documents
    /home/alice/documents/report.txt
    /home/alice/projects/myapp/main.py

    The / operator automatically handles the separator for you. No more worrying about whether to add a slash or not.

    Old way with os.path.join()
    import os
    path = os.path.join('/home', 'alice', 'docs')
    # String manipulation, easy to mess up
    Modern way with pathlib
    from pathlib import PurePosixPath
    path = PurePosixPath('/home') / 'alice' / 'docs'
    # Clean, readable, type-safe

    Changing file names and extensions

    Path objects have methods to swap out the file name or extension, which is handy for creating related files.

    Changing names and extensions
    from pathlib import PurePosixPath
    original = PurePosixPath('/data/report.csv')
    # Change the extension
    as_json = original.with_suffix('.json')
    print(f'JSON version: {as_json}')
    # Change the entire file name
    backup = original.with_name('backup.csv')
    print(f'Backup file: {backup}')
    # Change just the stem (keep extension)
    new_stem = original.with_stem('summary')
    print(f'New stem: {new_stem}')
    Output
    JSON version: /data/report.json
    Backup file: /data/backup.csv
    New stem: /data/summary.csv

    How Do You Search for Files with Glob Patterns?

    On a real filesystem, Path objects can search for files using glob patterns - simple wildcard expressions. The * matches any sequence of characters, and ** matches any number of directories.

    Since we can't access a real filesystem here, let's learn the patterns and practice with PurePosixPath.match(), which checks if a path matches a glob pattern.

    Matching paths with glob patterns
    from pathlib import PurePosixPath
    # Simulate a list of file paths
    files = [
    PurePosixPath('project/main.py'),
    PurePosixPath('project/utils.py'),
    PurePosixPath('project/data.csv'),
    PurePosixPath('project/README.md'),
    PurePosixPath('project/tests/test_main.py'),
    ]
    # Find all Python files
    print('Python files:')
    for f in files:
    if f.match('*.py'):
    print(f' {f}')
    print()
    # Find all files in the tests directory
    print('Test files:')
    for f in files:
    if f.match('tests/*'):
    print(f' {f}')
    Output
    Python files:
      project/main.py
      project/utils.py
      project/tests/test_main.py
    
    Test files:
      project/tests/test_main.py

    Common glob patterns you'll use:

  • *.py - All Python files
  • *.txt - All text files
  • test_* - Files starting with test_
  • **/*.py - All Python files in any subdirectory
  • data/* - Everything directly inside the data folder
  • Why Choose pathlib Over os.path?

    Before pathlib (added in Python 3.4), everyone used os.path for file path manipulation. Both work, but pathlib is generally better for new code.

    os.path (old way)
    import os
    
    path = '/home/alice/report.txt'
    print(os.path.basename(path))    # report.txt
    print(os.path.dirname(path))     # /home/alice
    print(os.path.splitext(path)[1]) # .txt
    new = os.path.join('/home', 'bob', 'file.txt')
    pathlib (modern way)
    from pathlib import PurePosixPath
    
    path = PurePosixPath('/home/alice/report.txt')
    print(path.name)    # report.txt
    print(path.parent)  # /home/alice
    print(path.suffix)  # .txt
    new = PurePosixPath('/home') / 'bob' / 'file.txt'

    Key advantages of pathlib:

  • Readable - Properties like .name and .parent are clearer than os.path.basename() and os.path.dirname().
  • Chainable - You can chain operations: path.parent / 'sibling.txt'.
  • Object-oriented - Path objects carry their data with them instead of passing strings to functions.
  • Cross-platform - Automatically handles / vs \ on different operating systems.
  • Chaining pathlib operations
    from pathlib import PurePosixPath
    # Chaining operations - clean and readable
    project = PurePosixPath('/home/alice/projects/webapp/src/app.py')
    # Get the project root (two levels up from the file)
    project_root = project.parent.parent
    print(f'Project root: {project_root}')
    # Create a path to the config file in the project root
    config = project_root / 'config.json'
    print(f'Config file: {config}')
    # Create a test file alongside the source file
    test_file = project.parent / f'test_{project.stem}.py'
    print(f'Test file: {test_file}')
    Output
    Project root: /home/alice/projects/webapp
    Config file: /home/alice/projects/webapp/config.json
    Test file: /home/alice/projects/webapp/src/test_app.py

    What Is a Common pathlib Pattern?

    Here's a practical pattern: organizing files by their extension. This shows how pathlib makes file organization logic clean and readable.

    Organizing files by extension
    from pathlib import PurePosixPath
    # Simulate downloaded files
    downloads = [
    'photo.jpg', 'report.pdf', 'notes.txt',
    'song.mp3', 'data.csv', 'image.png',
    'essay.pdf', 'track.mp3'
    ]
    # Organize by extension
    folders = {}
    for filename in downloads:
    p = PurePosixPath(filename)
    ext = p.suffix.lstrip('.')
    if ext not in folders:
    folders[ext] = []
    folders[ext].append(p.name)
    for ext, files in sorted(folders.items()):
    print(f'{ext}: {files}')
    Output
    csv: ['data.csv']
    jpg: ['photo.jpg']
    mp3: ['song.mp3', 'track.mp3']
    pdf: ['report.pdf', 'essay.pdf']
    png: ['image.png']
    txt: ['notes.txt']

    Practice Exercises

    Extract Path Components
    Write Code

    Given the path /home/user/documents/essay.txt, create a PurePosixPath and print the file name, the suffix (extension), and the parent directory, each on its own line.

    Expected output:

    essay.txt
    .txt
    /home/user/documents
    from pathlib import PurePosixPath
    # Your code here
    Predict the Joined Path
    Predict Output

    What does this code print? Think about how the / operator joins paths.

    from pathlib import PurePosixPath
    
    base = PurePosixPath('/home/alice')
    result = base / 'projects' / 'app' / 'main.py'
    print(result)
    from pathlib import PurePosixPath
    base = PurePosixPath('/home/alice')
    result = base / 'projects' / 'app' / 'main.py'
    print(result)
    Change File Extension
    Write Code

    Given the path /data/report.csv, use pathlib to create a new path with the extension changed to .json. Print both the original and new path.

    Expected output:

    Original: /data/report.csv
    Converted: /data/report.json
    from pathlib import PurePosixPath
    original = PurePosixPath('/data/report.csv')
    # Your code here
    Fix the Path Joining Bug
    Fix the Bug

    This code tries to build a path by concatenating strings, but it produces an incorrect result. Fix it to use pathlib's / operator.

    Expected output:

    /home/user/docs/notes.txt
    from pathlib import PurePosixPath
    base = PurePosixPath('/home/user')
    result = str(base) + 'docs' + 'notes.txt'
    print(result)
    Filter Files by Extension
    Write Code

    Given a list of file paths, use pathlib to filter only the .py files and print their stem (filename without extension), one per line, in alphabetical order.

    File list: ['app/main.py', 'app/utils.py', 'app/data.csv', 'app/config.json', 'app/test_app.py']

    Expected output:

    main
    test_app
    utils
    from pathlib import PurePosixPath
    files = ['app/main.py', 'app/utils.py', 'app/data.csv', 'app/config.json', 'app/test_app.py']
    # Your code here

    Related Tutorials

    Was this tutorial helpful?