xonsh

.. raw:: html

<img src="https://avatars.githubusercontent.com/u/17418188?s=200&v=4" alt="Xonsh shell icon." align="left" width="100px">

Xonsh (sounds like "consh") is a full-featured and cross-platform Python-based shell. The language is a superset of Python 3 with seamless integration of shell functionality and commands. It works on all major systems including Linux, macOS, and Windows. Xonsh is meant for the daily use of experts and novices.

.. raw:: html

<br clear="left"/>

.. list-table:: :widths: 1 1

• • Xonsh is the Shell
  • Xonsh is Python

• • .. code-block:: shell

    cd $HOME

    id $(whoami) > ~/id.txt

    cat /etc/passwd | grep root

    $PROMPT = '@ '

  • .. code-block:: python

    2 + 2

    var = "hello".upper()

    @.imp.json.loads('{"a":1}')

    [i for i in range(0,10)]

• • Xonsh is the Shell in Python
  • Xonsh is Python in the Shell

• • .. code-block:: python

    len($(curl -L https://xon.sh))

    $PATH.append('/tmp')

    p'/etc/passwd'.read_text().find('usr')

    $(@json podman ps --format json)['ID']

  • .. code-block:: python

    name = 'snail' echo @(name) > /tmp/@(name)

    with p'/tmp/dir'.mkdir().cd(): touch @(input('File: '))

    aliases['e'] = 'echo @(2+2)' aliases['a'] = lambda args: print(args)

• • Xonsh is Everywhere
  • Xonsh is an Ecosystem

• • .. code-block:: python

    $PATH

    ['/bin', '/sbin'] # Linux

    ['/homebrew/bin'] # macOS

    ['/usr/local/bin'] # FreeBSD

    ['/mnt/c/Windows/System32'] # WSL

    [r'c:\Windows\System32'] # Windows

    ['/nix/store/0-python/bin'] # Nix

    ['/data/termux/usr/bin'] # Termux

    ['/tmp/.mount_x/usr/bin/'] # AppImage

    ['/app/bin'] # Flatpak

    $PATH = ['/my/own/path']

  • .. code-block:: python

    xontrib load term_integration
    prompt_starship
    powerline
    dracula
    chatgpt
    django
    jupyter
    1password
    github_copilot
    history_encrypt

• • Xonsh is a Meta-Shell
  • Xonsh is User-extensible

• • .. code-block:: python

    xontrib load sh
    fish_completer

    def nudf(cmd): return @.imp.pandas.DataFrame( @.imp.json.loads( $(nu -c @(cmd+'| to json')))) nudf!(ls -la)

    aliases['ai'] = 'ollama run llama3' ai! how to remove images in podman

  • .. code-block:: python

    @events.on_ptk_create def custom_keybindings(bindings, **kw): @bindings.add(Keys.ControlI) def say_whoami(event): echo $(whoami)

    @events.on_postcommand def _prompt_err_cmd(cmd, rtn, out, ts): if rtn != 0: $XONSH_PROMPT_NEXT_CMD = cmd.rstrip()

If you like xonsh, :star: the repo and spread the word about xonsh.

.. class:: center

.. image:: https://img.shields.io/badge/Zulip%20Community-xonsh-green
        :target: https://xonsh.zulipchat.com/
        :alt: Join to xonsh.zulipchat.com

.. image:: https://repology.org/badge/tiny-repos/xonsh.svg
        :target: https://repology.org/project/xonsh/versions
        :alt: repology.org

.. image:: https://img.shields.io/badge/Docker%20Hub-xonsh-blue
        :target: https://hub.docker.com/u/xonsh
        :alt: hub.docker.com

.. image:: https://img.shields.io/badge/AppImage-xonsh-lightblue
        :target: https://xon.sh/appimage.html
        :alt: AppImage

.. image:: https://github.com/xonsh/xonsh/actions/workflows/test.yml/badge.svg
        :target: https://github.com/xonsh/xonsh/actions/workflows/test.yml
        :alt: GitHub Actions

.. image:: https://codecov.io/gh/xonsh/xonsh/branch/master/graphs/badge.svg?branch=main
        :target: https://codecov.io/github/xonsh/xonsh?branch=main
        :alt: codecov.io

First steps

---

• Installation <https://xon.sh/install.html>_ - isolated environment, package, container or portable AppImage.
• Tutorial <https://xon.sh/tutorial.html>_ - step by step introduction in xonsh.
• Cheat sheet <https://github.com/anki-code/xonsh-cheatsheet>_ - some beginners may find this a helpful place to start.

Extensions

---

Xonsh has an extension/plugin system. We call these additions xontribs.

• Xontribs on Github <https://github.com/topics/xontrib>_
• Awesome xontribs <https://github.com/xonsh/awesome-xontribs>_
• Core xontribs <https://xon.sh/api/_autosummary/xontribs/xontrib.html>_
• Create a xontrib step by step from template <https://github.com/xonsh/xontrib-template>_

Projects that use xonsh or compatible

---

• Assistant <https://gitlab.com/waser-technologies/technologies/assistant>_: An AI-powered shell with a full Xonsh terminal and a multi-agent LLM system.
• CrateDB <https://github.com/crate>_: The Database for Real-Time Analytics and Hybrid Search.
• conda <https://conda.io/projects/conda/en/latest/>_ and mamba <https://mamba.readthedocs.io/en/latest/>_: Cross-platform package managers.
• Starship <https://starship.rs/>_: Cross-shell prompt.
• zoxide <https://github.com/ajeetdsouza/zoxide>_: A smarter cd command.
• gitsome <https://github.com/donnemartin/gitsome>_: Supercharged Git/shell autocompleter with GitHub integration.
• xxh <https://github.com/xxh/xxh>_: Using xonsh wherever you go through the SSH.
• kash <https://github.com/jlevy/kash>_: The knowledge agent shell.
• Snakemake <https://snakemake.readthedocs.io/en/stable/snakefiles/rules.html#xonsh>_: A workflow management system to create reproducible and scalable data analyses.
• any-nix-shell <https://github.com/haslersn/any-nix-shell>_: xonsh support for the nix run and nix-shell environments of the Nix package manager.
• lix <https://github.com/lix-project/lix>_: A modern, delicious implementation of the Nix package manager.
• x-cmd <https://www.x-cmd.com/>_: x-cmd is a vast and interesting collection of tools guided by the Unix philosophy.
• rever <https://regro.github.io/rever-docs/>_: Cross-platform software release tool.
• Regro autotick bot <https://github.com/regro/cf-scripts>_: Regro Conda-Forge autoticker.

Jupyter-based interactive notebooks via xontrib-jupyter <https://github.com/xonsh/xontrib-jupyter>_:

• Jupyter and JupyterLab <https://jupyter.org/>_: Interactive notebook platform.
• Euporie <https://github.com/joouha/euporie>_: Terminal based interactive computing environment.
• Jupytext <https://jupytext.readthedocs.io/>_: Clear and meaningful diffs when doing Jupyter notebooks version control.

Compiling, packaging, or accelerating xonsh:

• AppImage <https://github.com/appimage>_ is a format for distributing Linux applications and can be used to create a standalone xonsh package <https://xon.sh/appimage.html>_.
• Nuitka <https://github.com/Nuitka/Nuitka>_ is an optimizing Python compiler that can build a native xonsh binary <https://github.com/xonsh/xonsh/issues/2895#issuecomment-3665753657>_.
• RustPython <https://github.com/RustPython/RustPython/>_ is a Python interpreter written in Rust that can run xonsh on top of Rust <https://github.com/xonsh/xonsh/issues/5082#issue-1611837062>_.

Welcome to the xonsh shell community

---

The xonsh shell is developed by a community of volunteers. There are a few ways to help out:

• Write a note or an article about xonsh.
• Send a link to Xonsh to your favorite blogger.
• Add xonsh support in third party tool: package manager <https://github.com/topics/package-manager>, terminal emulator <https://github.com/topics/terminal-emulators>, console tool <https://github.com/topics/console>, IDE <https://github.com/topics/ide>.
• Give a star to xonsh repository and to xontribs <https://github.com/topics/xontrib>_ you like.
• Solve a popular issue <https://github.com/xonsh/xonsh/issues?q=is%3Aissue+is%3Aopen+sort%3Areactions-%2B1-desc>_ or high priority issue <https://github.com/xonsh/xonsh/issues?q=is%3Aopen+is%3Aissue+label%3Apriority-high+sort%3Areactions-%2B1-desc>_ or a good first issue <https://github.com/xonsh/xonsh/issues?q=is%3Aopen+is%3Aissue+label%3A%22good+first+issue%22+sort%3Areactions-%2B1-desc>. You can start with the Developer guide <https://xon.sh/devguide.html>. Feel free to use LLM e.g. Github Copilot <https://github.com/copilot>_.
• Take an idea <https://github.com/xonsh/xontrib-template/issues?q=is%3Aopen+is%3Aissue+label%3Aidea+sort%3Areactions-%2B1-desc>_ and create a new xontrib <https://github.com/xonsh/xontrib-template#why-use-this-template>_.
• Contribute to xonsh API <https://github.com/xonsh/xonsh/tree/main/xonsh/api>_.
• Become xonsh core developer by deep diving into xonsh internals. E.g. we feel a lack of Windows support.
• Test xonsh with compiler, interpreter, optimizer and report upstream issues (e.g. Nuitka <https://github.com/xonsh/xonsh/issues/2895#issuecomment-3665753657>, RustPython <https://github.com/xonsh/xonsh/issues/5082#issue-1611837062>).
• Design more logos and images <https://github.com/anki-code/xonsh-logo>, improve xonsh website <https://xon.sh/> (src <https://github.com/xonsh/xonsh/blob/12f12ce94f1b6c92218e22fbdaaa846e16ac8b2d/docs/_templates/index.html#L9>_).
• Become a sponsor to xonsh <https://github.com/sponsors/xonsh>_.

We welcome new contributors!

Credits

---

• Thanks to Zulip <https://zulip.com/>_ for supporting the xonsh community <https://xonsh.zulipchat.com/>_!
• Thanks to HELLOTUX <https://www.hellotux.com/>_ for distributing the xonsh t-shirts, backpacks and more <https://www.hellotux.com/xonsh>_!
• Thanks to ADS.FUND for supporting xonsh token <https://ads.fund/token/0xadf7478450b69a349ed9634b18584d2d3da81464>_!