---
id: runs
version: "1.3.0"
license: MIT
license_treatment: permissive
maintenance: aging
---

# runs — 🏃 Run a block of text as a subprocess 🏃

License: permissive · Maintenance: aging · Downloads: 4.8M/mo

## What it is and what it does

runs is a wrapper around Python's subprocess module that lets you execute multiple commands in a single call by passing a block of text. Instead of calling subprocess.run() once per command, you write your commands as a multi-line string (or list), and runs splits them, handles comments and line continuations, and returns results for each command. It provides drop-in replacements for subprocess.call(), check_call(), check_output(), and run(), all with UTF-8 encoding by default instead of bytes.

The main problem it solves is the friction of running sequential subprocess commands in Python: normally you either loop and call subprocess repeatedly, or manually split and parse command strings. runs handles the parsing, encoding defaults, and optional features like echo logging and exception handling in one place. It does not support shell features like pipes, redirection, or environment variable expansion—those still require shell=True and manual handling.

Use it for:

- Run a sequence of shell commands from a Python script without looping subprocess calls.
- Execute build or deployment steps (compilation, copying files, cleanup) as a text block.
- Test harnesses that need to run multiple CLI tools and collect their output as strings.
- Batch system administration tasks (disk checks, log rotation, service restarts) from Python.
- Development scripts that chain multiple command-line tools and need UTF-8 output by default.

## Worth the install?

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

Runs multiple subprocess commands from a text block or list, with UTF-8 encoding by default, line continuations, comments, and optional logging and error handling.

Yes, if you frequently run multiple subprocess commands in sequence and want cleaner syntax and UTF-8 defaults. The low install friction and permissive license make it a low-risk add. However, the aging maintenance status (192 days since last release) means it is stable but not actively developed—suitable for stable use cases, not for packages expecting ongoing feature work or rapid bug fixes.

## Install

pip install runs
uv add runs
poetry add runs

## Installing runs

Before you install: Low install friction with a single pure-Python dependency (xmod). Maintenance status is aging—last release was 192 days ago—so expect no active development, though the package is stable for its current scope.

License in practice: MIT license permits commercial and private use with minimal restrictions, requiring only license and copyright notice retention.

Quickstart:

import runs

runs('''
    echo "hello"
    ls -la
    echo "done"
''')

Requires Python 3.10 or later. Note that shell features like pipes, redirection, and environment variable expansion do not work—only direct command execution.

Verify before relying:

- Whether xmod dependency is actively maintained or has its own aging/stability concerns.
- Real-world performance characteristics when running hundreds or thousands of commands in sequence.

## Package facts

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

## Tags

run multiple subprocess commands, batch subprocess execution, text block command runner, subprocess wrapper, shell command batch, multiline command execution, subprocess with utf-8, subprocess-wrapper, batch-execution

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