---
id: pytest-shutil
version: "1.8.1"
license: MIT license
license_treatment: permissive
maintenance: aging
---

# pytest-shutil — A goodie-bag of unix shell and environment tools for py.test

License: permissive · Maintenance: aging · Downloads: 220.9K/mo

## What it is and what it does

pytest-shutil is a collection of pytest fixtures and helper functions designed to simplify testing of shell scripts, command-line tools, and code that interacts with the filesystem or environment. It centers on a workspace fixture—a function-scoped temporary directory with convenience methods for running commands and managing files—plus utilities for controlling environment variables, changing directories, managing umasks, and executing subprocesses with output capture and coverage integration.

The package wraps common Unix testing patterns into reusable pytest fixtures and context managers, reducing boilerplate in test suites that need to spawn processes, manipulate the environment, or work with temporary file hierarchies. It depends on pytest, six, execnet, termcolor, and importlib-metadata, and targets Python 3.6 and later.

Use it for:

- Test shell scripts or command-line tools by running them in isolated workspaces and capturing their output.
- Verify code behavior under different environment variable configurations using set_env and unset_env context managers.
- Run Python functions or modules as if they were entry points, useful for testing CLI entry points or subprocess isolation.
- Manage temporary directories with automatic cleanup in test fixtures, avoiding manual tempfile boilerplate.
- Execute subprocesses with coverage instrumentation to measure test coverage of spawned processes.

## Worth the install?

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

Provides pytest fixtures and utilities for managing temporary workspaces, running shell commands, and controlling environment variables in automated tests.

Yes, with conditions. The package is stable and permissively licensed, with low install friction and no known vulnerabilities. However, maintenance is aging—the last release was 623 days ago—so adopt it only if you need its specific pytest fixtures for shell and environment testing and can accept slower response to future pytest or Python version changes.

## Install

pip install pytest-shutil
uv add pytest-shutil
poetry add pytest-shutil

## Installing pytest-shutil

Before you install: Low install friction with a pure-Python wheel distribution. Maintenance status is aging—last release was 623 days ago, though the repository remains active with recent commits and no archived status.

License in practice: MIT license permits free use, modification, and distribution with minimal restrictions, making it suitable for both open-source and commercial projects.

Quickstart:

pip install pytest-shutil

# In conftest.py or test file:
pytest_plugins = ['pytest_shutil']

def test_example(workspace):
    path = workspace.workspace
    script = path / 'test.sh'
    script.write_text('#!/bin/sh\necho hello')
    workspace.run('test.sh')

Verify before relying:

- Whether the workspace fixture's path object behavior remains stable after migration from path.py to pathlib in version 1.8.0
- Current compatibility with pytest versions beyond 4.0.0 and Python 3.13

## Package facts

- License: MIT license (permissive)
- Python support: supports_current
- Install friction: low
- Maintenance: aging
- Downloads: 220.9K/month (top 15,000 on PyPI)
- Known vulnerabilities: none known

## Tags

pytest fixtures for testing, shell command execution in tests, temporary workspace management, environment variable control, subprocess testing utilities, unix shell test helpers, pytest test environment setup, pytest-plugin, shell-testing, subprocess-management

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