Path portability

The most common source of Windows breakage in Python tools written on Linux is path construction. 'data/' + 'file.csv' produces a forward-slash path that Windows cannot always parse correctly. String concatenation with os.path.join works but is verbose. pathlib.Path replaces both approaches with an operator that is correct on every platform by construction.

The separator problem

Windows uses \ as a path separator; Linux and macOS use /. Python's string operations know nothing about this distinction:

# Breaks on Windows — produces 'data/file.csv' which Windows tolerates in some
# contexts but fails in others, and '\' is never produced for subdirectories.
path = 'data/' + 'file.csv'

# Also fragile — you must remember every edge case.
path = os.path.join('data', 'subdir', 'file.csv')

pathlib.Path uses the correct separator for the current OS automatically:

from pathlib import Path

path = Path('data') / 'subdir' / 'file.csv'
# On Linux/macOS: data/subdir/file.csv
# On Windows:     data\subdir\file.csv

The / operator on Path objects is path joining, not division. It reads naturally and handles every separator edge case correctly.

Absolute paths for the user's home directory

Path.home() returns the user's home directory on every platform without inspecting environment variables or hard-coding paths:

config_file = Path.home() / '.config' / 'mytool' / 'settings.toml'

On Linux this produces /home/alice/.config/mytool/settings.toml; on macOS /Users/alice/.config/mytool/settings.toml; on Windows C:\Users\alice\.config\mytool\settings.toml. The code is identical on all three.

Path.cwd() returns the current working directory, equivalent to os.getcwd() but returning a Path object ready for further composition.

Platform-correct config and cache directories with platformdirs

Placing config files in ~/.config is correct on Linux but not on macOS (which prefers ~/Library/Application Support) or Windows (%APPDATA%). The platformdirs library handles this without any conditional logic:

from platformdirs import user_config_dir, user_cache_dir

config_dir = Path(user_config_dir("mytool", "MyOrg"))
cache_dir  = Path(user_cache_dir("mytool", "MyOrg"))

config_dir.mkdir(parents=True, exist_ok=True)

Install platformdirs with pip install platformdirs. It is a zero-dependency package and is already a transitive dependency of many common tools, so it is rarely an additional install in practice.

Practical rule

One simple rule covers most cases: never construct a path with string concatenation or f-strings. Use Path(...) / part / part for every path, and Path.home() or platformdirs for any path that depends on the user's environment. That is the entire discipline of path portability.

Where to go next

Next: platform-specific behaviour — case sensitivity, line endings, signals, and how to detect the current OS when conditional logic is genuinely unavoidable.