pathlib

library1.0.1pypypi✓ verified 24d ago

The `pathlib` module provides an object-oriented interface for handling filesystem paths, simplifying path manipulations and making code more readable and concise compared to traditional modules like `os.path`. It has been part of Python's standard library since Python 3.4. The PyPI package 'pathlib' (version 1.0.1) is a backport for Python 3.3 and earlier, and Python 2.6/2.7. The module's features evolve with each Python version.

serialization data

# For Python 3.4 and later, pathlib is part of the standard library and does not require installation.

package ↗homepage ↗

INSTALL

IMPORT

SIG · PATHLIB

pathlib

serializationpythonv1.0.1

Install

1.6s avg

Import

11ms

Disk

65MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v1.0.1 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

py 3.10–3.910 runs

installs and imports cleanly · install 0.0s · import 0.013s · 65.8MB

glibc

py 3.10–3.910 runs

installs and imports cleanly · install 1.6s · import 0.010s · 18MB

65MB installed

● package 65MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

Path

✓ from pathlib import Path

✗ import pathlib; pathlib.Path('file.txt')

Importing Path directly is generally preferred for brevity and clarity.

This quickstart demonstrates creating a `Path` object, ensuring a directory exists, writing and reading text to/from a file, and accessing common path properties. It concludes with a cleanup of the created directory and file.

import os from pathlib import Path # Create a path object current_dir = Path.cwd() example_dir = current_dir / "my_data" example_file = example_dir / "report.txt" # Ensure the directory exists example_dir.mkdir(exist_ok=True) # Write to a file example_file.write_text("This is a test report.\n") print(f"Created file: {example_file.resolve()}") # Read from a file content = example_file.read_text() print(f"File content: {content.strip()}") # Check properties print(f"Is it a file? {example_file.is_file()}") print(f"File name: {example_file.name}") print(f"File suffix: {example_file.suffix}") print(f"Parent directory: {example_file.parent.name}") # Clean up (optional) example_file.unlink() example_dir.rmdir() print("Cleaned up example directory and file.")

Debug

Known issues

gotchaAvoid converting `Path` objects to strings (`str(path_obj)`) too early, as this loses all the benefits of the `Path` object's methods and object-oriented features. Most modern Python functions and libraries (since Python 3.6, including `open()`, `shutil.copy()`, `json.load`/`json.dump`, `subprocess.run`) natively accept `Path` objects.

fix

Pass `Path` objects directly to functions that support `os.PathLike` (which `Path` implements). Convert to string only when absolutely necessary for older APIs that strictly require `str`.

affects: Python 3.6+

deprecatedThe `pathlib` PyPI backport (version 1.0.1) is no longer maintained. For Python 2.7, `pathlib2` is the recommended and more actively maintained backport to provide similar functionality to the standard library `pathlib`.

fix

For Python 2.7, use `pip install pathlib2` and `from pathlib2 import Path`. For Python 3.4+, use the built-in `pathlib` module directly.

affects: Python 2.6, 2.7, 3.2, 3.3

breakingThe semantics of certain methods, like `Path.iterdir()`, can change between major Python versions. For instance, in Python 3.13, `Path.iterdir()` started evaluating a portion of the generator eagerly, potentially raising `FileNotFoundError` earlier if the directory doesn't exist, which was not the case in 3.12 (lazy evaluation).

fix

Always ensure the directory exists before calling `iterdir()` if the path might not exist. Be aware of potential subtle behavioral changes across Python versions when relying on specific iterator or generator evaluation timings.

affects: Python 3.13+

gotchaWhile `pathlib` provides `PurePosixPath` and `PureWindowsPath` for platform-agnostic path manipulation, using them explicitly can lead to `NotImplementedError` if you try to instantiate a platform-specific concrete path (e.g., `WindowsPath` on Unix) directly or if I/O operations are attempted with a `PurePath` object. Use `Path` for platform-appropriate concrete paths unless you specifically need pure path operations without I/O or cross-platform path *representation*.

fix

For general file system operations on the current system, always use `pathlib.Path` which instantiates the correct concrete path for the platform. Only use `PurePath`, `PurePosixPath`, or `PureWindowsPath` when you explicitly intend to manipulate paths purely computationally without touching the filesystem, or to represent paths for a different OS.

affects: All versions

gotchaMixing `pathlib` objects with functions from the `os` or `os.path` modules can negate `pathlib`'s benefits, often requiring unnecessary `str()` conversions. `pathlib` aims to consolidate and replace most `os.path` functionality.

fix

Prioritize `pathlib` methods (e.g., `/` operator for joining, `.exists()`, `.is_file()`, `.glob()`, `.rglob()`, `.mkdir()`, `.unlink()`) over `os.path` functions. Only fall back to `os` or `shutil` when `pathlib` does not offer equivalent functionality (e.g., `shutil.copy` for copying files efficiently).

affects: All versions

Errors

Common errors & fixes

ImportError: No module named pathlib

`pathlib` became a standard library module in Python 3.4. This error typically occurs when running code with Python 2.x or an older Python 3.x version (before 3.4) without installing the backport, or when the `pathlib` backport package is not installed in the active environment.

fix

For Python 3.4 and newer, ensure you are using a compatible Python version. For Python 3.3 or Python 2.x, install the backport using `pip install pathlib`. If on Python 2.7, `pathlib2` is a more maintained alternative: `pip install pathlib2`.

AttributeError: module 'pathlib' has no attribute 'Path'

This error commonly arises when a user-created Python file is named `pathlib.py` in the same directory as the script being run, or within Python's import path. This causes the interpreter to import the local, empty `pathlib.py` instead of the standard library `pathlib` module, leading to the `Path` class not being found.

fix

Rename your custom Python file to something other than `pathlib.py` to avoid shadowing the standard library module.

TypeError: unsupported operand type(s) for /: 'Path' and 'str'

This error occurs when the `Path` object being used is not the `pathlib.Path` class from the standard library, often due to shadowing by a custom or another library's `Path` class. The standard `pathlib.Path` class *does* support the `/` operator with strings.

fix

Verify that you have correctly imported `from pathlib import Path`. If you have other path-related libraries installed, ensure there are no naming conflicts or shadowing, and fully qualify the import if necessary (e.g., `import pathlib; p = pathlib.Path('foo') / 'bar'`).

Upgrade

Version history

1.0.1latest on PyPI · released May 4, 2022

Audit

Dependencies

No dependency data recorded yet.

Agent activity

9 hits · last 30 days

node

Resources

packagehttps://pypi.org/project/pathlib/ ↗

homepagehttps://pathlib.readthedocs.org/ ↗