Shellingham: Tool to Detect Surrounding Shell

1.5.4 verified Tue May 12 auth: no python install: verified quickstart: verified

Shellingham is a Python library designed to detect the current shell environment, aiding in tasks like shell completion. The latest version is 1.5.4, released on March 28, 2026. It is actively maintained with a release cadence of approximately one release every few months.

pip install shellingham

Common errors

error ModuleNotFoundError: No module named 'shellingham' ↓

cause The `shellingham` library has not been installed in the current Python environment.

fix

pip install shellingham

error shellingham.ShellDetectionFailure: Could not detect shell ↓

cause `shellingham` was unable to determine the current shell environment, often due to a non-standard setup, missing `SHELL` environment variable, or running in an environment without an active shell process.

fix

Ensure the SHELL environment variable is correctly set, or that the execution environment allows shellingham to inspect process information. If the environment genuinely lacks a detectable shell, handle this exception in your code (e.g., by providing a fallback shell).

error ImportError: cannot import name 'detects_shell' from 'shellingham' ↓

cause You are attempting to import a function or class that either does not exist, or has a different name, within the `shellingham` library (e.g., a common typo like 'detects_shell' instead of 'detect_shell').

fix

Use the correct function or class name, such as detect_shell. For example: from shellingham import detect_shell.

error AttributeError: module 'shellingham' has no attribute 'get_shell_info' ↓

cause You are trying to access an attribute (like a function or class) on the `shellingham` module that does not exist or is misspelled. The primary function for detecting the shell is `detect_shell`.

fix

Use the correct attribute name, such as shellingham.detect_shell().

Warnings

breaking Version 1.5.0 introduced a breaking change in the detect_shell function's return type, which now returns a tuple instead of a single string. ↓

fix Update your code to handle the tuple return type from detect_shell.

deprecated The 'get_shell' function is deprecated as of version 1.5.0 and will be removed in a future release. ↓

fix Replace calls to 'get_shell' with 'detect_shell'.

breaking The `detect_shell` function can raise `shellingham._core.ShellDetectionFailure` if it fails to determine the current shell, which commonly occurs in environments without a clear shell context (e.g., certain container setups, non-interactive script execution, or environments where process introspection fails). ↓

fix Implement error handling for `shellingham._core.ShellDetectionFailure` around calls to `detect_shell` (e.g., using a `try-except` block) to gracefully handle scenarios where the shell cannot be detected.

Install compatibility verified last tested: 2026-05-12

python os / libc status wheel install import disk

3.10 alpine (musl) - - 0.00s 17.9M

3.10 slim (glibc) - - 0.00s 18M

3.11 alpine (musl) - - 0.00s 19.7M

3.11 slim (glibc) - - 0.00s 20M

3.12 alpine (musl) - - 0.00s 11.6M

3.12 slim (glibc) - - 0.00s 12M

3.13 alpine (musl) - - 0.00s 11.2M

3.13 slim (glibc) - - 0.00s 12M

3.9 alpine (musl) - - 0.00s 17.3M

3.9 slim (glibc) - - 0.00s 18M

Imports

detect_shell
```
from shellingham import detect_shell
```
Correct import path for the detect_shell function

Quickstart verified last tested: 2026-04-23

Quickstart example to detect and print the current shell environment.

from shellingham import detect_shell

shell, path = detect_shell()
print(f"Detected shell: {shell}")