os.path

—

Updated March 13, 2026 · Modules

path filesystem stdlib os

The os.path module is part of Python’s standard library and provides portable functions for working with file paths. It handles the differences between operating systems transparently — whether you’re on Windows, macOS, or Linux, these functions know how to construct and manipulate paths correctly. The module works with strings, bytes, or any object implementing the os.PathLike protocol, and it returns the same type as the input.

Syntax

import os.path

Or import directly:

from os.path import join, exists, isfile

Functions

os.path.join()

Join one or more path segments intelligently. The function inserts the correct separator (backslash on Windows, forward slash on Linux/macOS) between segments, and handles edge cases like trailing separators.

os.path.join(path, /, *paths)

Parameter	Type	Default	Description
`path`	`str` \| `bytes` \| `PathLike`	—	The first path segment. Position-only.
`*paths`	`str` \| `bytes` \| `PathLike`	—	Additional path segments to join.

Returns: The joined path as a string or bytes.

import os.path

# Basic joining
result = os.path.join('/home', 'user', 'documents')
print(result)
# /home/user/documents  (Linux/macOS)
# \\home\\user\\documents  (Windows)

# Handles separators correctly
print(os.path.join('/home/', '/user/'))
# /home/user

# Absolute paths reset the joining
print(os.path.join('/home/user', '/var/log'))
# /var/log

os.path.split()

Split a path into two parts: the directory (everything before the final separator) and the filename (everything after). This is useful when you need to separate the folder from the file name.

os.path.split(path, /)

Parameter	Type	Default	Description
`path`	`str` \| `bytes` \| `PathLike`	—	The path to split. Position-only.

Returns: A tuple of (directory, filename).

import os.path

# Split a file path
directory, filename = os.path.split('/home/user/documents/report.txt')
print(f"Directory: {directory}")
print(f"Filename: {filename}")
# Directory: /home/user/documents
# Filename: report.txt

# Works with trailing slashes (note: dirname becomes empty)
directory, filename = os.path.split('/home/user/')
print(f"Directory: '{directory}'")
print(f"Filename: '{filename}'")
# Directory: '/home/user'
# Filename: ''

os.path.exists()

Check whether a path exists. This returns True for files, directories, and symbolic links that point to existing destinations. It’s the most common way to verify that a path is valid before attempting to open or manipulate it.

os.path.exists(path)

Parameter	Type	Default	Description
`path`	`str` \| `bytes` \| `PathLike`	—	The path to check.

Returns: bool — True if the path exists, False otherwise.

import os.path

# Check if files or directories exist
print(os.path.exists('/etc/passwd'))   # Usually True on Linux
print(os.path.exists('/nonexistent'))  # False

# Common pattern: only create file if it doesn't exist
if not os.path.exists('config.json'):
    with open('config.json', 'w') as f:
        f.write('{}')

os.path.isfile()

Check if a path points to a regular file (not a directory, symlink, or device). This is useful when you need to verify that a path refers to an actual file before reading it.

os.path.isfile(path)

Parameter	Type	Default	Description
`path`	`str` \| `bytes` \| `PathLike`	—	The path to check.

Returns: bool — True if path is a regular file.

import os.path

# Check if paths are files
print(os.path.isfile('/etc/passwd'))   # True - it's a file
print(os.path.isfile('/etc/'))          # False - it's a directory
print(os.path.isfile('/nonexistent'))  # False - doesn't exist

# Filtering a list of paths to get only files
paths = ['/etc/passwd', '/etc', '/home/user/.bashrc']
files = [p for p in paths if os.path.isfile(p)]
print(files)
# ['/etc/passwd', '/home/user/.bashrc']

os.path.isdir()

Check if a path points to a directory. This is the counterpart to isfile() and is commonly used for directory traversal and validation.

os.path.isdir(path, /)

Parameter	Type	Default	Description
`path`	`str` \| `bytes` \| `PathLike`	—	The path to check. Position-only.

Returns: bool — True if path is a directory.

import os.path

# Check if paths are directories
print(os.path.isdir('/etc/'))      # True
print(os.path.isdir('/etc/passwd')) # False
print(os.path.isdir('/nonexistent')) # False

# Recursive directory creation with existence check
def ensure_directory(path):
    if not os.path.isdir(path):
        os.makedirs(path)

os.path.abspath()

Return the absolute (full) version of a path. This resolves relative paths like ./file.txt or ../data into complete paths starting from the root of the filesystem. It also normalizes the path by removing redundant separators.

os.path.abspath(path)

Parameter	Type	Default	Description
`path`	`str` \| `bytes` \| `PathLike`	—	The path to convert to absolute.

Returns: A string representing the absolute path.

import os.path

# Convert relative to absolute
print(os.path.abspath('document.txt'))
# /home/user/current_directory/document.txt  (full path)

print(os.path.abspath('../data/file.csv'))
# /home/user/data/file.csv

# Useful for logging - always show full paths
log_path = os.path.abspath('app.log')
print(f"Logging to: {log_path}")

os.path.relpath()

Return a relative filepath to either the current working directory or an optional start directory. This is useful for displaying paths in a more user-friendly way or for making paths portable.

os.path.relpath(path, start=os.curdir)

Parameter	Type	Default	Description
`path`	`str` \| `bytes` \| `PathLike`	—	The path to make relative.
`start`	`str` \| `PathLike`	`os.curdir`	The directory to make the path relative to.

Returns: A string representing the relative path.

import os.path

# Get relative path from current directory
print(os.path.relpath('/home/user/projects/app/main.py'))
# ../projects/app/main.py  (from /home/user)

# Relative to a specific start directory
print(os.path.relpath('/home/user/projects/app/main.py', '/home/user'))
# projects/app/main.py

# Useful for displaying to users
current_file = '/home/user/projects/app/config/settings.yaml'
print(f"Config file: {os.path.relpath(current_file)}")
# Config file: ../../config/settings.yaml

os.path.dirname()

Extract the directory portion of a path. This is a simpler alternative to split() when you only need the directory, not the filename.

os.path.dirname(path, /)

Parameter	Type	Default	Description
`path`	`str` \| `bytes` \| `PathLike`	—	The path to extract directory from. Position-only.

Returns: The directory path as a string.

import os.path

# Extract directory
print(os.path.dirname('/home/user/documents/file.txt'))
# /home/user/documents

print(os.path.dirname('/home/user/documents/'))
# /home/user/documents

# Often chained with other functions
file_path = '/var/log/nginx/access.log'
log_dir = os.path.dirname(file_path)
print(f"Log directory: {log_dir}")
# Log directory: /var/log/nginx

os.path.basename()

Extract the filename (the final component) from a path. Note that this differs from the Unix basename command — for /foo/bar/ (with trailing slash), Python’s basename returns an empty string, while the shell command returns bar.

os.path.basename(path, /)

Parameter	Type	Default	Description
`path`	`str` \| `bytes` \| `PathLike`	—	The path to extract filename from. Position-only.

Returns: The filename as a string.

import os.path

# Extract filename
print(os.path.basename('/home/user/documents/report.pdf'))
# report.pdf

print(os.path.basename('/home/user/'))
# ''  (empty string, unlike shell basename)

# Chaining with dirname to get both parts
full_path = '/opt/app/config/database.yml'
print(f"Directory: {os.path.dirname(full_path)}")
print(f"Filename: {os.path.basename(full_path)}")
# Directory: /opt/app/config
# Filename: database.yml

os.path.splitext()

Split a path into the root (everything before the extension) and the extension (starting with the final dot). This is the go-to function for changing file extensions.

os.path.splitext(path, /)

Parameter	Type	Default	Description
`path`	`str` \| `bytes` \| `PathLike`	—	The path to split. Position-only.

Returns: A tuple of (root, extension).

import os.path

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

# Common use: change file extension
def change_extension(filepath, new_ext):
    root, _ = os.path.splitext(filepath)
    return root + new_ext

print(change_extension('photo.jpg', '.png'))
# photo.png

# Handles paths with multiple dots
root, ext = os.path.splitext('archive.tar.gz')
print(f"Root: {root}")
print(f"Extension: {ext}")
# Root: archive.tar
# Extension: .gz

os.path.expanduser()

Expand the tilde (~) character to the user’s home directory. On Unix systems, it uses the HOME environment variable or looks up the password database. On Windows, it uses USERPROFILE or a combination of HOMEPATH and HOMEDRIVE.

os.path.expanduser(path)

Parameter	Type	Default	Description
`path`	`str` \| `bytes` \| `PathLike`	—	The path that may contain ~ or ~user.

Returns: The path with ~ expanded to the home directory.

import os.path

# Expand tilde to home directory
print(os.path.expanduser('~/documents'))
# /home/user/documents  (Linux)
# C:\Users\user\Documents  (Windows)

# Expand for another user (Unix)
print(os.path.expanduser('~root'))
# /root

# Commonly used for config files
config_path = os.path.expanduser('~/.myapp/config')
print(f"Config location: {config_path}")
# Config location: /home/user/.myapp/config

os.path.normpath()

Normalize a path by collapsing redundant separators and resolving .. and . references. This cleans up paths like A//B, A/B/, and A/./B into a canonical form.

os.path.normpath(path)

Parameter	Type	Default	Description
`path`	`str` \| `bytes` \| `PathLike`	—	The path to normalize.

Returns: The normalized path as a string.

import os.path

# Collapse redundant separators
print(os.path.normpath('/home//user///documents'))
# /home/user/documents

# Resolve parent directories
print(os.path.normpath('/home/user/../admin'))
# /home/admin

# Current directory reference
print(os.path.normpath('/home/./user/./files'))
# /home/user/files

# Mixed separators normalized on Windows
print(os.path.normpath('C:/users\\admin\\data'))
# C:\\users\\admin\\data  (Windows)
# C:/users/admin/data  (Linux treats forward slashes as-is)

# Useful for comparing paths
path1 = '/home/user/docs/../docs'
path2 = '/home/user/docs'
print(os.path.normpath(path1) == path2)
# True

Common Patterns

Building paths safely

Always use os.path.join() instead of string concatenation to build paths. This ensures your code works across operating systems:

import os.path

# Good: portable
config_path = os.path.join(os.path.expanduser('~'), '.myapp', 'config.json')

# Bad: breaks on Windows
config_path = '~' + '/.myapp' + '/' + 'config.json'

Checking before operations

A common pattern is to check existence before file operations:

import os.path

target = '/data/output.txt'

# Only read if it exists
if os.path.isfile(target):
    with open(target) as f:
        data = f.read()

# Create directory if missing
output_dir = os.path.dirname(target)
if output_dir and not os.path.isdir(output_dir):
    os.makedirs(output_dir)

Path resolution chain

Combine these functions for complex path manipulations:

import os.path

def resolve_config(base_dir, relative_path):
    """Resolve a relative config path to absolute."""
    joined = os.path.join(base_dir, relative_path)
    expanded = os.path.expanduser(joined)
    return os.path.normpath(os.path.abspath(expanded))

print(resolve_config('~/.config', '../app/settings.json'))
# /home/user/app/settings.json