---
id: runez
version: "5.9.1"
license: MIT
license_treatment: permissive
maintenance: active
---

# runez — Friendly misc/utils/convenience library

License: permissive · Maintenance: active · Downloads: 1.6M/mo

## What it is and what it does

runez is a lightweight utility library that wraps common system operations—running subprocesses, reading and writing files, managing directories—with a consistent interface for error handling and logging. It eliminates boilerplate by providing sensible defaults: operations abort on failure by default with clear error messages, but can be set to return False instead via fatal=False. The library includes a dryrun mode to preview operations without executing them, and a CaptureOutput context manager to intercept output from any code section.

The package is pure Python with no external dependencies, making it trivial to add to any project. It supports current Python versions (3.10 through 3.14) and has been actively maintained since 2018. Most operations follow a consistent signature pattern, so once you learn the conventions for fatal, logger, and dryrun parameters, you can predict how any function will behave.

Use it for:

- Build scripts and CLI tools that need to run external commands and fail fast with readable errors.
- Test suites that need to capture and verify logging output or subprocess output from tested code.
- Automation scripts that benefit from dryrun mode to preview file operations before committing them.
- Utilities that perform file I/O (read, write, copy, delete) with consistent error handling across operations.
- Logging setup in small projects where a full logging framework feels like overkill.

## Worth the install?

AI-flagged interpretation of the facts above — verify before relying.

A zero-dependency utility library providing common file operations, subprocess execution, logging setup, and output capture with consistent error handling and dryrun support.

Yes. runez is a low-risk, actively maintained utility with zero dependencies, permissive licensing, and a clear design philosophy. Install it if you write scripts or tools that repeatedly wrap subprocess calls, file operations, or logging setup—it will reduce boilerplate and standardize error handling. Not necessary for projects that already use a heavier framework or that have minimal I/O needs.

## Install

pip install runez
uv add runez
poetry add runez

## Installing runez

Before you install: Low friction: pure Python, no runtime dependencies, distributed as a wheel. Actively maintained with recent commits; last release 101 days ago.

License in practice: MIT license permits unrestricted use, modification, and distribution in proprietary and open-source projects alike.

Quickstart:

pip install runez

import runez

output = runez.run("ls", "foo")
runez.copy("foo", "bar")
runez.write("foo", "content\n")

Requires Python 3.10 or later.

Verify before relying:

- Whether the library's error messages and logging output meet your project's standards for verbosity and format.
- Performance characteristics when handling very large files or many concurrent operations.

## Package facts

- License: MIT (permissive)
- Python support: supports_current
- Install friction: low
- Maintenance: active
- Downloads: 1.6M/month (top 5,000 on PyPI)
- Known vulnerabilities: none known

## Tags

subprocess wrapper with error handling, file operations utility library, logging setup helper, capture output context manager, dryrun mode for scripts, subprocess-wrapper, file-operations, zero-dependency

[View on SkillFed](https://skillfed.io/packages/runez) · [View on PyPI](https://pypi.org/project/runez/)