# shellingham

> Tool to Detect Surrounding Shell

- **URL**: https://www.freshcrate.ai/projects/shellingham
- **Author**: Tzu-ping Chung
- **Category**: Developer Tools
- **Latest version**: `1.5.4` (2026-04-21)
- **License**: ISC License
- **Source**: https://github.com/sarugaku/shellingham
- **Language**: Python
- **GitHub**: 311 stars, 41 forks
- **Registry**: pypi (`shellingham`)
- **Tags**: `pypi`, `shell`

## Description

=============================================
Shellingham: Tool to Detect Surrounding Shell
=============================================

.. image:: https://img.shields.io/pypi/v/shellingham.svg
    :target: https://pypi.org/project/shellingham/

Shellingham detects what shell the current Python executable is running in.


Usage
=====

.. code-block:: python

    >>> import shellingham
    >>> shellingham.detect_shell()
    ('bash', '/bin/bash')

``detect_shell`` pokes around the process's running environment to determine
what shell it is run in. It returns a 2-tuple:

* The shell name, always lowercased.
* The command used to run the shell.

``ShellDetectionFailure`` is raised if ``detect_shell`` fails to detect the
surrounding shell.


Notes
=====

* The shell name is always lowercased.
* On Windows, the shell name is the name of the executable, minus the file
  extension.


Notes for Application Developers
================================

Remember, your application's user is not necessarily using a shell.
Shellingham raises ``ShellDetectionFailure`` if there is no shell to detect,
but *your application should almost never do this to your user*.

A practical approach to this is to wrap ``detect_shell`` in a try block, and
provide a sane default on failure

.. code-block:: python

    try:
        shell = shellingham.detect_shell()
    except shellingham.ShellDetectionFailure:
        shell = provide_default()


There are a few choices for you to choose from.

* The POSIX standard mandates the environment variable ``SHELL`` to refer to
  "the user's preferred command language interpreter". This is always available
  (even if the user is not in an interactive session), and likely the correct
  choice to launch an interactive sub-shell with.
* A command ``sh`` is almost guaranteed to exist, likely at ``/bin/sh``, since
  several POSIX tools rely on it. This should be suitable if you want to run a
  (possibly non-interactive) script.
* All versions of DOS and Windows have an environment variable ``COMSPEC``.
  This can always be used to launch a usable command prompt (e.g. `cmd.exe` on
  Windows).

Here's a simple implementation to provide a default shell

.. code-block:: python

    import os

    def provide_default():
        if os.name == 'posix':
            return os.environ['SHELL']
        elif os.name == 'nt':
            return os.environ['COMSPEC']
        raise NotImplementedError(f'OS {os.name!r} support not available')

## Recent releases

| Version | Date | Urgency | Changes |
| --- | --- | --- | --- |
| `1.5.4` | 2026-04-21 | Low | Imported from PyPI (1.5.4) |
| `1.5.0.post1` | 2023-01-03 | Low | ## What's Changed * Add syntax highlighting to readme by @swaldhoer in https://github.com/sarugaku/shellingham/pull/63 * Limit package installation to Python >= 3.7 by @hswong3i in https://github.com/sarugaku/shellingham/pull/62  ## New Contributors * @swaldhoer made their first contribution in https://github.com/sarugaku/shellingham/pull/63 * @hswong3i made their first contribution in https://github.com/sarugaku/shellingham/pull/62  **Full Changelog**: https://github.com/sarugaku/shelli |
| `1.5.0` | 2022-08-04 | Low | ## What's Changed * Bump bleach from 3.2.1 to 3.3.0 by @dependabot in https://github.com/sarugaku/shellingham/pull/44 * Bump cryptography from 3.3.1 to 3.3.2 by @dependabot in https://github.com/sarugaku/shellingham/pull/45 * Bump urllib3 from 1.26.3 to 1.26.4 by @dependabot in https://github.com/sarugaku/shellingham/pull/46 * Modern python by @JeppeKlitgaard in https://github.com/sarugaku/shellingham/pull/50 * Update README.rst by @davidlatwe in https://github.com/sarugaku/shellingham/pull |
| `1.3.1` | 2019-04-10 | Low | Fix a typo that prevents ash and csh from being detected. |
| `1.3.0` | 2019-04-09 | Low | Add [Almquist shell](https://en.wikipedia.org/wiki/Almquist_shell) (`ash`) detection support. |
| `1.2.8` | 2019-04-09 | Low | - Parse `ps` output according to how it is actually formatted, instead of incorrectly using `shlex.split()`. - Improve process parsing on Windows to so executables with non-ASCII names are handled better. |
| `1.2.7` | 2019-04-09 | Low | - Suppress subprocess errors from `ps` if the output is empty. |
| `1.2.6` | 2019-04-09 | Low | Minor Python 3 compatibility fix. |
| `1.2.5` | 2019-04-09 | Low | * Improve `/proc` content parsing robustness to not fail with non-decodable command line arguments. |
| `1.2.4` | 2019-04-09 | Low | - Fix exception on Windows when the executable path is too long to fit into the PROCESSENTRY32 struct. Generally the shell shouldn't be buried this deep, and we can always fix it when that actually happens, if ever. |

## Citation

- HTML: https://www.freshcrate.ai/projects/shellingham
- Markdown: https://www.freshcrate.ai/projects/shellingham.md
- Dependencies JSON: https://www.freshcrate.ai/api/projects/shellingham/deps

_Generated by freshcrate.ai. Indexes pypi releases for AI-agent ecosystem packages._