py library

1.11.0 verified Tue May 12 auth: no python install: verified quickstart: verified

The 'py' library provides a collection of powerful, low-level utilities primarily focused on filesystem path manipulation, INI parsing, I/O, Python code introspection, and logging. Maintained by the pytest-dev team, it often serves as a foundational component for other testing and development tools. It is currently at version 1.11.0 and has a stable release cadence.

pip install py

Common errors

error ModuleNotFoundError: No module named 'py' ↓

cause This error occurs when the 'py' library is not installed in the current Python environment or Python cannot find it in the configured paths.

fix

Install the 'py' library using pip: pip install py

error AttributeError: module 'py' has no attribute 'path' ↓

cause This error often arises in `pytest` contexts when trying to use `py.path.local`, which is a legacy fixture. Modern `pytest` versions encourage the use of `tmp_path` which returns a `pathlib.Path` object instead. It can also be caused by a local file or directory named 'py' shadowing the installed library.

fix

If using pytest, replace tmpdir (which returns py.path.local) with tmp_path (which returns pathlib.Path). For example, change tmpdir.join('file.txt') to tmp_path / 'file.txt'. If it's a shadowing issue, rename any local 'py.py' files or 'py/' directories.

error OSError: [Errno 2] ENOENT ↓

cause This 'Error NO ENTry' signifies that a file or directory path provided to a 'py.path.local' operation (or similar filesystem interaction) does not exist or cannot be found at the specified location.

fix

Ensure that the file or directory path you are trying to access or create actually exists and is correctly specified. Use methods like py.path.local(path).check() to verify existence before operations, or ensure parent directories are created with ensure=True if writing a file or mkdir() if creating a directory.

Warnings

gotcha For new projects or general file system path manipulation, Python's built-in `pathlib` module (introduced in Python 3.4) is often the more idiomatic and recommended choice over `py.path`. `pathlib` provides a fully object-oriented interface for paths and is part of the standard library. ↓

fix Consider using `from pathlib import Path` and its methods (`Path.cwd()`, `Path.joinpath()`, `Path.read_text()`, etc.) for modern Python development. `py.path` remains useful for compatibility with projects built around it (e.g., `pytest`) or for its specific utility functions.

gotcha The `py.log` module provides basic logging facilities. However, for robust application logging, structured logging, or integration with existing logging ecosystems, Python's standard `logging` module is generally more powerful and flexible, offering advanced features like handlers, formatters, and hierarchical loggers. ↓

fix Evaluate whether Python's standard `logging` module meets your requirements for application-wide logging before opting for `py.log` for general use cases.

gotcha The `py.code` module offers powerful introspection and manipulation of Python code objects, often utilized by testing frameworks like `pytest`. Directly relying on `py.code` for general-purpose introspection or metaprogramming in application code might lead to less standard or harder-to-maintain solutions. Python's `inspect` module or `ast` module typically provide more standard APIs for these tasks. ↓

fix For common code introspection needs, explore Python's standard `inspect` module. For code modification or static analysis, consider the `ast` module.

Install compatibility verified last tested: 2026-05-12

python os / libc status wheel install import disk

3.10 alpine (musl) - - 0.04s 18.6M

3.10 slim (glibc) - - 0.03s 19M

3.11 alpine (musl) - - 0.05s 20.6M

3.11 slim (glibc) - - 0.02s 21M

3.12 alpine (musl) - - 0.01s 12.5M

3.12 slim (glibc) - - 0.02s 13M

3.13 alpine (musl) - - 0.01s 12.1M

3.13 slim (glibc) - - 0.01s 13M

3.9 alpine (musl) - - 0.04s 18.1M

3.9 slim (glibc) - - 0.03s 19M

Imports

path
```
import py.path; p = py.path.local('.')
```
Accessing the path utilities.

code

import py.code; c = py.code.Source('print("hello")')

Accessing code introspection utilities.

io
```
import py.io; cap = py.io.StdCapture()
```
Accessing I/O capturing utilities.

log

import py.log; py.log.setconsumer(my_consumer)

Accessing logging utilities.

Quickstart verified last tested: 2026-04-23

This quickstart demonstrates basic file system operations using `py.path.local`, including creating a directory, writing to a file, reading from it, and cleaning up. This highlights the object-oriented approach to path manipulation provided by the `py` library.

import py
import os

# Create a temporary local path object
temppath = py.path.local('my_temp_dir')
temppath.ensure(dir=True) # Ensure it's a directory

# Join paths and write content
filepath = temppath.join('hello.txt')
filepath.write('Hello, py world!')

# Read content
print(filepath.read())

# Cleanup
filepath.remove()
temppath.remove()