pshell: get rid of all bash scripts

Bash is widely regarded as a very poor choice to write any script longer than a few lines. No auto-testing or auto-documentation support, bug-prone grammar, and lack of debugging tools beyond echo make any substantial bash script intrinsically fragile and hard to maintain.

Python on the other hand is a very robust language; however some operations that could be performed in bash with a single line can take a disproportionate amount of code when written in Python using os, shutil, subprocess, etc.

pshell gets the best of both worlds by providing a unified, robust, and compact Python API to perform all the tasks that would be traditionally done through bash scripting.

To clarify: pshell is not an interactive shell; however nothing stops you from using it from your favourite python/ipython/jupyter terminal!

Some of the core features:

• All actions are logged using the logging module. This is invaluable for auditing and debugging. It is strongly recommended to initialise the logging module and set the loglevel to INFO or DEBUG before invoking pshell.

• All file paths can contain bash-style environment variables, which are resolved on the fly. Failure to resolve an environment variable results in an EnvironmentError being raised. You’re safe from the dreaded rm -rf $MISSPELLED/*!

• Functions from the core library are wrapped, hardened, polished, and occasionally changed to have a saner default behaviour.

• Full pathlib support, also when wrapping standard library functions that do not support it, such as shutil and glob.

Quick start

>>> import logging
>>> import pshell as sh
>>> logging.basicConfig(
...     level=logging.INFO,
...     format='%(asctime)s %(levelname)s [%(filename)s:%(lineno)d] %(message)s'
>>> )
>>> with sh.open("hello.txt", "w") as fh:
...     fh.write("Hello world!")
2026-01-14 13:15:43,045 INFO [myscript.py:7] Opening 'hello.txt' for write
>>> sh.mkdir("somedir")
2026-01-14 13:16:08,503 INFO [myscript.py:9] Creating directory somedir
>>> sh.copy("hello.txt", "somedir/")
2026-01-14 13:16:30,468 INFO [myscript.py:10] Copying hello.txt to somedir/

Index

• Installation
  • Required dependencies
  • Installing with conda
  • Installing with pip
  • Minimum dependency versions
• Development Guidelines
  • Reporting issues
  • Deploying a development environment
  • Test
  • Code Formatting
  • Documentation
• What’s New
  • v1.7.0 (unreleased)
  • v1.6.0 (2026-01-14)
  • v1.5.0 (2025-12-28)
  • v1.4.0 (2024-03-15)
  • v1.3.0 (2022-03-26)
  • v1.2.0 (2020-07-01)
    • Code changes
    • Packaging changes
    • CI changes
  • v1.1.0 (2018-11-19)
  • v1.0.0 (2018-10-11)

API Reference

• Shell commands
  • call()
  • check_call()
  • check_output()
  • real_fh()
  • CalledProcessError
  • TimeoutExpired
• Environment variables
  • source()
  • putenv()
  • override_env()
  • resolve_env()
• Manage files and directories
  • remove()
  • chdir()
  • pushd()
  • move()
  • copy()
  • backup()
  • symlink()
  • exists()
  • lexists()
  • mkdir()
  • owner()
• Logging
  • Setting and retrieving the pshell logger
    • set_global_logger()
    • context_logger
    • get_logger()
  • Using the pshell logger
    • debug()
    • info()
    • warning()
    • error()
    • critical()
    • inc_stacklevel()
• File manipulation
  • concatenate()
• Open file handles
  • open()
• Running processes
  • find_procs_by_cmdline()
  • kill()
  • killall()
  • wait_for_server()
• File search and file system traversal
  • glob()
  • iglob()
  • FileMatchError

Thread safety

pshell is fully thread safe and compatible with free-threading/noGIL interpreters. If thread safety is required, it is strongly recommended to use Python 3.14 or later; pshell does not work around bugs in earlier Python versions.

Credits

pshell was initially developed internally since 2014 as landg.bash by Legal & General. It was renamed and open-sourced in 2018.

License

This software is available under the open source Apache License.