Shell Escape for Python

3.8.1 · active · verified Sun Apr 12

The `shellescape` Python module provides the `shellescape.quote()` function, which is a backport of Python 3.8's `shlex.quote()` functionality. It safely escapes strings for use as single tokens within shell commands, mitigating shell injection vulnerabilities when executing external commands from Python scripts. The library is currently active, with its latest release `v3.8.1` in January 2020.

Warnings

gotcha Prefer `shlex.quote` directly on Python 3.3+ (especially 3.8+). The `shellescape` library is a backport designed for older Python versions (Python 2.x and 3.x < 3.3). Using it on modern Python where `shlex.quote` is natively available is redundant and may introduce subtle behavioral differences if the backport diverges from the latest CPython implementation.
Fix: On Python 3.3 and newer, use `from shlex import quote` directly. Only use `shellescape` if targeting environments where `shlex.quote` is not present.
gotcha Understand that `shellescape.quote()` escapes *individual* tokens. It does not magically make an entire command string safe if other parts are unescaped or if `shell=True` is used improperly with complex commands. The safest approach is to use `subprocess.run()` with a list of arguments (i.e., `shell=False`, which is the default) to avoid shell interpretation entirely.
Fix: Always pass arguments as a list to `subprocess.run()` (e.g., `subprocess.run(['command', arg1, arg2])`). If `shell=True` is strictly required, ensure *every* user-controlled component in the command string is individually escaped using `shellescape.quote()` or `shlex.quote()`.
breaking Version `3.8.1` included a bugfix (`#2`) that changed the definition of the quote regex to align with CPython v3.8.1 and removed `re.ASCII` for Python 2 support. While this was a bugfix to improve correctness, it means the escaping behavior might differ subtly from previous `shellescape` versions if code relied on the prior (buggy) definition.
Fix: Review any code that relies on `shellescape.quote()`'s exact output, especially when upgrading from versions prior to `3.8.1`, and test against the new behavior.

Install

pip install shellescape Install stable version

Imports

quote
```
from shellescape import quote
```
The primary function is `quote`, directly imported from the `shellescape` package. There is no `shlex` submodule within `shellescape`.

Quickstart

This quickstart demonstrates how to import the `quote` function and use it to escape user-provided input. The escaped string can then be safely embedded as a single token in a shell command string. While `shellescape` facilitates constructing shell command strings, the general best practice for executing external commands in Python is to pass arguments as a list to `subprocess.run()` (which defaults to `shell=False`) to avoid shell interpretation entirely.

from shellescape import quote
import subprocess

user_input = "my file with spaces; evil command"
safe_argument = quote(user_input)

# Best practice: pass arguments as a list to subprocess.run for security (shell=False is default)
# However, shellescape is used when you absolutely need to construct a shell string
# For demonstration, we'll show how to use the escaped string in a shell command string:
command = f"echo {safe_argument}"

print(f"Original input: '{user_input}'")
print(f"Escaped argument: '{safe_argument}'")
print(f"Constructed command: '{command}'")

# Example of safe execution (though direct list is preferred when possible)
# DO NOT use shell=True with unescaped user input.
# If shell=True is necessary, ensure all user-provided tokens are escaped.
# For this example, we demonstrate the output of the escaped string:
# subprocess.run(command, shell=True, check=True)

view raw JSON →