shellescape

library3.8.1pypypi✓ verified 23d ago

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.

auth-security

pip install shellescape

github ↗package ↗

INSTALL

IMPORT

SIG · SHELLESCAPE

shellescape

auth-securitypythonv3.8.1

Install

1.5s avg

Import

—

Disk

16MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v3.8.1 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

py 3.10–3.95 runs

installs and imports cleanly · install 0.0s · import 0.000s · 17.8MB

glibc

py 3.10–3.95 runs

installs and imports cleanly · install 1.5s · import 0.000s · 18MB

16MB installed

● package 16MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

quote

✓ from shellescape import quote

✗ import shellescape; shellescape.shlex.quote()

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

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)

Debug

Known issues

gotchaPrefer `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.

affects: < 3.3 (when `shlex.quote` is unavailable)

gotchaUnderstand 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()`.

affects: All versions

breakingVersion `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.

affects: < 3.8.1

Errors

Common errors & fixes

No module named 'shellescape'

The `shellescape` package has not been installed in the current Python environment.

fix

pip install shellescape

AttributeError: module 'shlex' has no attribute 'quote'

The `shlex.quote()` function is not available in the Python version being used (e.g., Python 2.x or Python 3.0-3.2), which is why `shellescape` was created as a backport.

fix

Install the `shellescape` library (`pip install shellescape`) and use `shellescape.quote()` instead.

TypeError: expected a string, bytes or bytearray object, got ...

The `shellescape.quote()` function was called with an argument that is not a string, bytes, or bytearray type.

fix

Ensure the input to `shellescape.quote()` is a string, bytes, or bytearray object. Convert other types to a string if necessary (e.g., `str(value)`).

Upgrade

Version history

3.8.1latest on PyPI · released Jan 25, 2020

Audit

Dependencies

No dependency data recorded yet.

Agent activity

17 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/chrissimpkins/shellescape ↗

packagehttps://pypi.org/project/shellescape/ ↗