Cheat sheet for the xonsh shell with copy-pastable examples. This is a good level of knowledge to start being productive.

If you like the cheatsheet click ⭐ on the repo and tweet about it.

What is xonsh?

Xonsh is a Python-powered, cross-platform, Unix-gazing shell language and command prompt. The language is a superset of Python 3.6+ with additional shell primitives that you are used to from Bash and IPython. It works on all Python-compatible systems, including Linux, macOS, and Windows. The xonsh shell is developed by a community of 300+ volunteers and the xonsh philosophy based on the principle of cooperation.

If you don't want to learn step by step jump to demo examples.

What does xonsh mean?

The "xonsh" word sounds like conch [kɑːntʃ] - a common name of a number of different sea snails or shells (🐚, @). Thus "xonsh" is the reference to the "shell" word that is commonly used to name command shells.

Over time the approach to replace a letter in the words to "x" and pronounce as short /k/ when used with vowels (e.g. "xat" sounds like "cat" [kæt]) became the way to create unique names for xonsh related solutions e.g. xontrib, xonfig, xunter. Adding "x" in the beginning is also the way to create xonsh-related name e.g. xpip.

Fun fact: when you run xonsh on *nix in the home directory the default prompt looks like user@host ~ @ - it's a nice visual metaphor of snail (~) that lives in the conch (@) and the conch is the home for snail.

You can find more visuals around xonsh in xonsh-logo repository.

Install xonsh

There are three ways to use xonsh:

Simple xonsh install. You can use the system installed Python to install xonsh and dependencies. This is a good option if you don't plan to manage Python versions or virtual environments.
Install xonsh with package and environment management system. In this way you can flexibly manage the Python version, dependencies, and virtual environments, but because xonsh is a Python-based shell you have to understand what you're doing and the section below will provide some guidance.
Try xonsh without installation. Use xonsh container or the Linux AppImage to run and try xonsh.
The best way to install xonsh as core shell. You must read the previous sections before using this.

Simple xonsh install

Most modern operating systems have Python and PyPi (pip) that are preinstalled or that can be installed easily. By installing from PyPi you will get the latest version of the xonsh shell. We highly recommend using the full version of the xonsh PyPi-package with prompt-toolkit on board:

python -m pip install 'xonsh[full]'

On any system you can install python and then install xonsh from pip i.e., any_pkg_manager install python && python -m pip install 'xonsh[full]'. This is the preferable way.

If you have python but no pip just install it using ensurepip:

python -m ensurepip --upgrade
pip -V

Another way is to install xonsh from the package manager that is supplied by the operating system. This way is not recommended in operating systems without the rolling release concept the xonsh shell version may be very old (check latest xonsh release or versions of xonsh across platforms) because the average release cycle for the xonsh shell is quarter.

# Not recommended (old version, maybe not full dependencies installed) but possible:
apt install xonsh     # Debian/Ubuntu
dnf install xonsh     # Fedora
brew install xonsh    # OSX
pacman -S xonsh       # Arch Linux

Install xonsh with package and environment management system

Xonsh is a Python-based shell, and to run xonsh you must have Python installed. The Python version and its packages can be installed and located anywhere: in the operating system directories, as part of a virtual environment, as part of the user directory, or as a virtual drive created temporarily behind the scenes by the Linux AppImage.

The first thing you have to remember is that when you execute import or any other Python code during a xonsh session, it will be executed in the Python environment that was used to run the current instance of xonsh. Use the xc alias to check the xonsh context.

In other words, you can activate a virtual environment during a xonsh session (using mamba, conda, rye, pyenv, pipx) but the current session will continue to use packages from the environment that was used to run xonsh. And if you want to run xonsh with the packages from the currently activated virtual environment you have to install xonsh in that environment and run it directly. Keep in mind current $PATH and as result which xonsh when running something.

Thus the second thing you should remember is that when you run xonsh in a virtual environment it will try to load xonsh RC files (i.e. ~/.xonshrc) and because the virtual environment is different from the environment you ordinarily use, the loading of the RC file will tend to fail because of the lack of the appropriate set of packages. When you write your ~/.xonshrc it's good practice to check the existing external dependencies before loading them. See also xontrib-rc-awesome and xonsh context alias.

Install xonsh on macOS or Linux using conda

Here is the real life example but mostly created for educational reasons. See the best way to install xonsh in the next section.

You can use Conda (or faster replacement - mamba) with Conda-forge to install and use xonsh.

#
# Install python using brew
#
zsh  # Default macOS shell
# Install brew from https://brew.sh/
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
brew install python  # or `python@3.11`

#
# Install Miniconda from https://docs.conda.io/en/latest/miniconda.html 
# (example for Mac, use the link for your platform)
#
cd /tmp
wget https://repo.anaconda.com/miniconda/Miniconda3-latest-MacOSX-arm64.sh
chmod +x Miniconda3-latest-MacOSX-arm64.sh
./Miniconda3-latest-MacOSX-arm64.sh
# Add conda init code that was printed to `~/.zshrc` and restart zsh.
# Or run `/Users/username/miniconda3/bin/conda init zsh` to add init to ~/.zshrc and restart zsh.

# After restarting zsh you will see `(base)` in prompt.
# This means that you're in the conda `base` environment.

# Switch to Conda-forge channel
conda config --add channels conda-forge
conda config --set channel_priority strict 
conda update --all --yes

# Install xonsh to the `base` environment
conda install xonsh
conda init xonsh  # Add init to ~/.xonshrc. You can also add `$CONDA_AUTO_ACTIVATE_BASE='false'` to avoid conda loading at start

which xonsh
# /Users/username/miniconda3/bin/xonsh

# Run xonsh from the `base` environment
xonsh

How to work and understand the environments in conda:

# `xpip` is used to install packages to the current xonsh session location (now it's `base` environment)
xpip install ujson  

# Example of creating the environment with a certain version of Python
conda search python | grep 3.10
conda create -n "py310" python=3.10 xonsh

conda activate py310
# Now the environment is `py310` but current xonsh session is still in `base` environment

which xonsh
# /Users/username/miniconda3/envs/py310/bin/xonsh

which pip
# /Users/username/miniconda3/envs/py310/bin/pip  # pip from `py310`

which xpip
# /Users/username/miniconda3/bin/pip  # pip from `base` environment from where xonsh ran

# Run xonsh that installed in `py310` environment from xonsh run in `base` environment
xonsh
conda activate py310
# Now xonsh session is in `py310` environment and the current environment is also `py310`

import ujson
# No module named 'ujson'   # YES because ujson was installed in `base` environment

On Mac we also recommend installing GNU coreutils to use the Linux default tools (i.e. ls, grep):

brew install coreutils
$PATH.append('/opt/homebrew/opt/coreutils/libexec/gnubin')  # add to ~/.xonshrc

How to understand the xonsh location

Which xonsh and which Python used to run the current xonsh session:

import sys
[sys.argv[0], sys.executable]
# ['/opt/homebrew/bin/xonsh', '/opt/homebrew/opt/python@3.11/bin/python3.11']


@(sys.executable) -m site
# Full info about paths

Which xonsh and which python that will be executed to run new instances depends on the list of directories in $PATH or virtual environment:

$PATH
# ['/home/user/miniconda3/bin', '/opt/homebrew/bin]

[$(ls -la @$(which xonsh)), $(ls -la @$(which python)), $(python -V)]
# ['/home/user/miniconda3/bin/xonsh', '/home/user/miniconda3/bin/python -> python3.11', 'Python 3.11.1']

python -m site
# Full info about paths

pipx and xonsh

The pipx tool is also good for installing xonsh in case you need a certain Python version:

# Install Python before continuing
pip install pipx
pipx install --python python3.8 xonsh  # Here `python3.8` is the path to installed python. 
pipx run xonsh 
# or add /home/$USER/.local/bin to PATH (/etc/shells) to allow running just the `xonsh` command

The best way to install xonsh as core shell

When xonsh becomes a core shell it's needed to keep python environment with xonsh stable, predictable and independent of any changes in the system. To forget about the cases where manipulations around python and packages break the shell unintended you can install xonsh with xonsh-install.

Note! We do not recommend to use xonsh as a default login shell if you are not feel you strong and experienced. Because of most tools are waiting that login shell is POSIX-compliant you can face with issues when some tool is trying to run sh commands in xonsh.

Try xonsh without installation

Container

Using open source Podman is recommended but docker also ok.

# Container with specific Python version and latest release of xonsh
podman run --rm -it python:3.11-slim /bin/bash \
 -c "pip install 'xonsh[full]' && xonsh"

# Container with specific Python version and xonsh from the master branch
podman run --rm -it python:3.11-slim /bin/bash \
 -c "apt update && apt install -y git && pip install -U git+https://github.com/xonsh/xonsh && xonsh"

# Official xonsh container image may have an old version
podman run --rm -it xonsh/xonsh:slim

Linux-portable AppImage contains both Python 3 and xonsh in one file

wget https://github.com/xonsh/xonsh/releases/latest/download/xonsh-x86_64.AppImage -O xonsh
chmod +x xonsh
./xonsh

# Then if you don’t have Python on your host, you can access it from the AppImage by running:
$PATH = [$APPDIR + '/usr/bin'] + $PATH
python -m pip install tqdm --user  # the `tqdm` package will be installed to ~/.local/
import tqdm

You can build your own xonsh AppImage with the packages you need in 15 minutes.

Xonsh basics

The xonsh language is a superset of Python 3 with additional shell support. As a result, you can mix shell commands and Python code as easily as possible. Right off the bat examples:

cd /tmp && ls                     # shell commands

21 + 21                           # python command

for i in range(0, 42):            # mix python 
    echo @(i+1)                   # and the shell

len($(curl https://xon.sh))       # mix python and the shell

xpip install xontrib-dalias && xontrib load dalias
y = $(@yaml dig +yaml google.com)  # convert output into object
y[0]['message']['query_time']

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


$PATH.append('/tmp')              # using environment variables

p'/etc/passwd'.read_text().find('root')  # path-string returns Path 
                                         # (https://docs.python.org/3/library/pathlib.html)

for line in $(cat /etc/passwd).splitlines():  # read the lines from the output
    echo @(line.split(':')[0])                # prepare line on Python and echo

for file in gp`*.*`:              # reading the list of files as Path-objects
    if file.exists():             # using rich functionality of Path-objects
        du -sh @(file)            # and pass it to the shell command

import json                       # python libraries are always at hand
if info := $(podman info --format '{{json .}}'):
    print('ContainersRunning:', json.loads(info)['ContainersRunning'])

xpip install xontrib-prompt-bar   # xonsh has huge amount of powerful extensions
xontrib load prompt_bar           # follow the white rabbit - https://github.com/topics/xontrib

# Finally fork https://github.com/anki-code/xontrib-rc-awesome
# to convert your ~/.xonshrc into a pip-installable package 
# with the extensions you need on board.

Looks nice? Install xonsh!

Most frequent things that newcomers totally overlook

1. Shell commands, also known as subprocess commands

The first thing you should remember is that the shell commands are not the calls of another shell (i.e. bash). Xonsh has its own parser implementation for subprocess commands, and this is why a command like echo {1..5} \; (brace expansion and escape characters in bash) won't work. Most sh-shell features can be replaced by sane Python alternatives. For example, the earlier command could be expressed as echo @(range(1,6)) ';'.

If you think that only xonsh has the sh-uncompatible elements in its parser, you are mistaken. If we compare Bash and Zsh we will find that pip install package[subpackage] command will work in Bash but in Zsh the error will be raised because Zsh has a special meaning for square braces. It's normal to have an evolution in the syntax and features.

Be calm and accept the sane and self-consistent Python-driven mindset.

Note:

Most novices try to copy and paste sh-lang commands that contain special characters and get syntax errors in xonsh. If you want to run environment agnostic sh-lang's commands that you copy from the internet just use the macro call in xonsh bash -c! echo {123} or use xontrib-sh to run context-free bash commands in xonsh by adding ! at the beginning of the command.
We highly recommend to taking a look at the section Install xonsh with package and environment management system.

2. Strings and arguments in shell commands

The second potential misunderstanding comes from the first. Use quotes to escape special characters, the special meaning of braces, or pass a string as an argument. When in doubt, use quotes!

You should clearly understand the difference:

sh-lang shells

xonsh

1. Has an escape character:

echo 123\ 456
# 123 456

1. Use quotes:

echo "123 456"
# 123 456

Escape character to wrap and so on:

echo "123\
456"
# 123456

2. Open the quotes:

echo --arg="val"
# --arg=val

# and:

echo --arg "val"
# --arg val

2. Save quotes:

echo --arg="val"
# --arg="val"

# But if argument quoted entirely:

echo --arg "val"
# --arg val

3. Brackets have no meaning:

echo {123} [456]
# {123} [456]

3. Brackets have meaning:

echo {123} [456]
# SyntaxError

echo "{123}" '[456]'
# {123} [456]

Note:

You can wrap any argument into Python string substitution:

name = 'snail'
echo @('--name=' + name.upper())
# --name=SNAIL

You can use the showcmd command to show the arguments list:

showcmd echo The @('args') @(['list', 'is']) $(echo here) "and" --say="hello" to @([]) you
# ['echo', 'The', 'args', 'list', 'is', 'here', 'and', '--say="hello"', 'to', 'you']]

3. The process substitution operator `$()` returns output with universal new lines

In sh-compatible shells, the process substitution operator $() executes the command and then splits the output and uses those parts as arguments. The command echo $(echo -e "1 2\n3") will have three distinct arguments, 1, 2 and 3 that will passed to the first echo.

In xonsh shell the $() operator is smarter (xonsh >= 0.17.0):

Return the line if it's single line e.g. $(whoami) will return 'user'.
Return universal new lines for multiple lines e.g. $(ls) will return '1\n2\n3\n'.
Finally you can use xontrib-dalias to have a list of lines e.g. l = $(@lines cat file).

Note:

To do what sh-compatible shells are doing with the $() operator, the xonsh shell has the @$() operator that will be described in the next chapter.
```
showcmd echo @$(echo "1\n2 3\n4")
# ['echo', '1', '2', '3', '4']
```

To transform the output you can use python substitution e.g. use splitlines:

showcmd echo @($(echo "1\n2 3\n4").splitlines())  # the first echo will get three arguments: "1", "2 3", "4"
# ['echo', '1', '2 3', '4']

4. Threading

Xonsh runs subprocess commands or callable aliases using threading prediction mechanism that simply called "threading" or "(un)threadable" words. This threading prediction was introduced to have an ability to capture any output from processes that are completely non interactive e.g. echo or grep. When you run !(echo 1) the echo process will be predicted as thredable and current terminal will be detached and stdout, stderr and everything will be captured.

The threading prediction mechanism:

It requires the clear understanding of how it works from the developer who want to use capturable operators with complex tasks.
It has edge cases and some expectations can't be realised without improving the xonsh core logic - it's mostly related to mixing callable aliases with subprocess command.

In the nuthesll when you try to run unthredable and uncapturable process (e.g. vim, ssh) in complex callable allias you can face with that callable alias is thredable by default and wrapping interactive tools into it ledas to cases where you need to have ninja knowledge about how it works in the xonsh core. If you have no this knowledge you will have stuck output as well as freezed and suspended processes at the end. But in more simpler cases it's needed to just add @unthredable to callable alias or change the operator from capturable to uncapturable.

The xonsh core team want to rid of threading prediction in the future but it's not so trivial task that requires to understand more about process management.

Finally here is the way of how to predict threading:

__xonsh__.commands_cache.predict_threadable(['echo'])
# True

__xonsh__.commands_cache.predict_threadable(['ssh'])
# False

How to change the predicted value using @thread and @unthread aliases you can find below :)

Operators

Overview

Operators:

$() is to run processes and capture the stdout. Almost the same as in traditional shells.
!() is to run sync or async threadable (capturable) processes. The terminal is detached for the process in this mode to deliver non-blocking behavior. To block the process and wait for result use .end(), .out, .rtn and other attributes that forces getting the result.
![] is to run processes without any capturing but return CommandPipeline with base info: pid, return code, timinig, etc. This operator is working when you run plain commands e.g. just echo hello.
$[] is to run processes without any capturing and any catching the result. Use it for uncapturable processes (e.g. vim) if you want to stream output directly to the terminal and without any capturing.

Examples:

id $(whoami)  # xonsh >= 0.17.0

worker1 = !(sleep 3)  # Non-blocking.
echo 'Something is happening while worker1 is working.'
if worker1.rtn == 0:  # Blocking. The `.rtn` attribute call has `.end()` under the hood.
    echo 'worker1 is done'
# Note. There is issue with this case that will be fixed in xonsh > 0.19.0.

file = p'~/.xonshrc'
if ![ls @(file)]:
    head @(file)

$[vim ~/.xonshrc]

From tech side (most of the behavior is dictated by OS):

Operator	`$()`	`!()`	`![]`	`$[]`
Blocking	yes	no	yes	yes
Capture stdout	yes	yes for threadable	no	strict no
Capture stderr	no	yes for threadable	no	strict no
Attach TTY input	yes	no	yes	yes
Attach TTY output	no for threadable	no for threadable	no for threadable	yes
Return	stdout	CommandPipeline	HiddenCommandPipeline	`None`

Here:

Threadable (capturable) process is the process without any interaction with user. Note that if unthreadable process will run with detached terminal it will be suspended by OS automatically.
Capturing "strict no" means that stream will be passed to the main terminal from any place of calling.

Note:

If you want to run interactive xonsh from bash script you need to have interactive shebang (i.e. #!/bin/bash -i) to avoid suspending by OS.

`$()` - capture and return output without printing stdout and stderr

Technical name of this operator: captured stdout. Python call: __xonsh__.subproc_captured_stdout().

Captures stdout and returns single line or miltiline output with universal new lines:

# xonsh >= 0.17.0

$(whoami)    # Python mode
# 'user'

id $(whoami)  # Subproc mode
# uid=501(user) gid=20(staff)

showcmd $(echo -e '1\n2\r3 4\r\n5')    # Subproc mode
# ['1\n2\n3 4\n5\n']

output = $(echo -e '1\n2\r3 4\r\n5')   # Python mode 
output
# '1\n2\n3 4\n5\n'

You can change the behavior by setting $XONSH_SUBPROC_OUTPUT_FORMAT (xonsh >= 0.17.0):

$XONSH_SUBPROC_OUTPUT_FORMAT = 'list_lines'

$(ls /)
# ['/bin', '/etc', '/home']

`!()` - capture all and return object without printing stdout and stderr

Technical name of this operator: captured object or full capturing with non blocking mode. Python call: __xonsh__.subproc_captured_object()

Captures stdout and returns CommandPipeline. Truthy if successful (returncode == 0), compares to, iterates over lines of stdout:

ret = !(echo 123)
ret
#CommandPipeline(
#  pid=404136,
#  returncode=0,
#  args=['echo', '123'],
#  alias=None,
#  timestamps=[1604742882.1826484, 1604742885.1393967],
#  executed_cmd=['echo', '123'],
#  input='',
#  output='123\n',
#  errors=None
#)   

if ret:
      print('Success')     
#Success

for l in ret:
      print(l)     
#123
#

Note! This is non blocking operator: no waiting for enging output. To get the output you need to convert an object to a string, invoke .end(), ask for .rtn or use the .out to force ending the process and read output from internal buffers:

r = !(ls /)
r.output
# ''

r.end()
r.output
# 'bin\netc\n...'

r = !(ls /)
r.out                # out is forcing ending
# 'bin\netc\n...'

r = !(ls /)
print(r)             # r will be converted to str and the ending will be forced
# bin
# etc
# ...

Note! When you're using full capturing the stdout and stderr will be captured and there will be no terminal (tty) connected. You can use this operator only for non interactive tools running. If you will do !(ls | fzf) or !(python -c "input()") the executed command will be suspended by POSIX OS (1, 2) because the process is waiting for input in background. Use uncaptured operators for interactive tools and read the futher materials around unthreadable mode to do things right.

`$[]` - not capturing (return `None`), print stdout and stderr

Technical name of this operator: uncaptured mode. Python call: __xonsh__.subproc_uncaptured().

Passes stdout to the screen and returns None:

ret = $[echo 123]
# 123
repr(ret)
# 'None'

This is the same as echo 123, but this syntax allows explicitly running a subprocess command.

`![]` - print stdout/stderr and return hidden object

Technical name of this operator: uncaptured hidden object. Python call: __xonsh__.subproc_captured_hiddenobject()

Note! The behavior may be different if $XONSH_CAPTURE_ALWAYS is True or False (default).

Passes stdout to the screen and returns HiddenCommandPipeline:

with __xonsh__.env.swap(XONSH_CAPTURE_ALWAYS=False):  # Default.
    r = ![echo -e '1\n2\r3 4\r\n5']
    # 1               # Stream output of the command
    # 3 4
    # 5
    r               # No return value because it's HiddenCommandPipeline object
    r.out           
    # ''            # Empty because `$XONSH_CAPTURE_ALWAYS = False`.
    r.returncode
    # 0

with __xonsh__.env.swap(XONSH_CAPTURE_ALWAYS=True):
    r = ![echo -e '1\n2\r3 4\r\n5']
    # 1               # Stream output of the command
    # 3 4
    # 5
    r               # No return value because it's HiddenCommandPipeline object
    r.out           # But it has the properties from CommandPipeline
    # '1\n2\r3 4\n5\n'
    r.returncode
    # 0

Elegant checking the result of the command using walrus operator:

if r := ![ls NO]:
    print(f'It works! Return code: {r.returncode}')
else:
    print(f'It fails! Return code: {r.returncode}')

# ls: cannot access 'NO': No such file or directory
# It fails! Return code: 2

This operator is used under the hood for running commands at the interactive xonsh prompt.

`@()` - use Python code as an argument or a callable alias

Evaluates Python and passes the arguments:

showcmd 'Supported:' @('string') @(['list','of','strings']) 
#['Supported:', 'string', 'list', 'of', 'strings']

echo -n '!' | @(lambda args, stdin: 'Callable' + stdin.read())
#Callable!

`@$()` - split output of the command by white spaces for arguments list

Technical name: captured inject output. API call: __xonsh__.subproc_captured_inject()

showcmd @$(echo -e '1\n2\r3 4\r\n5')
#['1', '2\r3', '4', '5']

This is mostly what bash's $() operator does.

Environment Variables

Three ways to get environment:

${...}  # Get the list of environment variables.

# Get the list of environment variables using Python syntax:
__xonsh__.env  # Get the list of environment variables using builtin reference to xonsh session (__xonsh__)

# Recommended for Python code and xontribs:
from xonsh.built_ins import XSH  # Import current xonsh session.
XSH.env  # Get the list of environment variables using xonsh session (XSH).

Operating with environment variables:

$VAR = 'value'    # Set environment variable

ENV = ${...}                # short typing
ENV.get('VAR', 'novalue')   # the good practice to have a fallback for missing value
# 'value'
ENV.get('VAR2', 'novalue')  # the good practice to have a fallback for missing value
# 'novalue'

'VAR' in ENV   # Check environment variable exists
#True

${'V' + 'AR'}     # Get environment variable value by name from expression
#'value'

print($VAR)
with ${...}.swap(VAR='another value', NEW_VAR='new value'):  # Change VAR for commands block
    print($VAR)
print($VAR)
#value
#another value
#value

$VAR='new value' xonsh -c r'echo $VAR'   # Change variable for subprocess command
#new value

__xonsh__.env.get('VAR', 'novalue')  # the way to call environment using the __xonsh__ builtin
# 'value'

Python and subprocess mode:

print("my home is $HOME")                        # Python mode
# my home is $HOME

print("my home is " + $HOME)                     # Python mode
# my home is /home/snail

echo "my home is $HOME" as well as '$HOME'       # Subprocess mode
# my home is /home/snail as well as /home/snail

Work with $PATH:

$PATH
# EnvPath(
# ['/usr/bin',
#  '/sbin',
#  '/bin']
# )

$PATH.append('/tmp')                             # Append path '/tmp' at end of $PATH list
$PATH.prepend('/tmp')                            # (xonsh>0.15.1) Insert path '/tmp' at front of $PATH list
$PATH.insert(0, '/tmp')                          # Insert path '/tmp' to appropriate position of $PATH list
$PATH.remove('/tmp')                             # Remove path '/tmp' (first match)

$PATH.add(p"~/bin", front=True, replace=True))   # Insert path '~/bin' at front of $PATH list and replace existing entries
$PATH.add(p"~/bin", front=True)                  # Insert path '~/bin' at front of $PATH list
$PATH.add(p"~/bin", front=False, replace=True))  # Insert path '~/bin' at end of $PATH list and replace existing entries

Note! Starting from xonsh 0.15.2 the logic was improved.

Setup local paths by prepending to path via a loop in .xonshrc:

import os.path
from os import path
$user_bins = [
    f'{$HOME}/.cargo/bin',
    f'{$HOME}/.pyenv/bin',
    f'{$HOME}/.poetry/bin',
    f'{$HOME}/bin',
    f'{$HOME}/local/bin',
    f'{$HOME}/.local/bin', 
]

for dir in $user_bins:
    if path.isdir(dir) and path.exists(dir):
        $PATH.add(dir,front=True, replace=True)

See also the list of xonsh default environment variables.

Aliases

Simple aliases

aliases['g'] = 'git status -sb'           # Add alias as string
aliases['e'] = 'echo @(2+2)'              # Add xonsh executable alias (ExecAlias)
aliases['gp'] = ['git', 'pull']           # Add alias as list of arguments
aliases['b'] = lambda: "Banana!\n"        # Add alias as simple callable lambda
aliases |= {'a': 'echo a', 'b':'echo b'}  # Add aliases from the dict
del aliases['b']                          # Delete alias

Easy wrapping a command by using ExecAlias with built-in $args (or $arg0, $arg1, etc) variable:

aliases['echo-new'] = "echo @($args) new"
$(echo-new hello)
# 'hello new\n'
$(echo-new -n hello)
# 'hello new'

Easy switch environment using alias:

aliases['lines'] = "$XONSH_SUBPROC_OUTPUT_FORMAT = 'list_lines'; echo $XONSH_SUBPROC_OUTPUT_FORMAT"
aliases['stream'] = "$XONSH_SUBPROC_OUTPUT_FORMAT = 'stream_lines'; echo $XONSH_SUBPROC_OUTPUT_FORMAT"
lines
# list_lines
$(ls)
# ['file1', 'file2', 'file3']
stream
# stream_lines
$(ls)
# 'file1\nfile2\nfile3\n'

Also with handy """-string to use " and ' without escaping:

aliases['scmd'] = """showcmd @([a for a in $args if a != "cutme"])"""

scmd
# usage: showcmd [-h|--help|cmd args]
# Displays the command and arguments as a list ...

scmd 1 2 cutme 3
#['1', '2', '3']

Function as an alias for group of commands

Ordinarily "alias" word refers to a subprogram that has exit code and arguments for subprocess mode. In xonsh you can group commands and reuse it as Python functions or classes:

def hello(name):
    echo hello @(name)

hello('Alex')
# hello Alex

or class:

class my:
    @classmethod
    def hello(cls, name):
        echo hello @(name)

my.hello('Alex')
# hello Alex

Alias that returns command

If you need to transform command use @aliases.return_command:

@aliases.register
@aliases.return_command
def _xsudo(args):
    """Sudo with expanding aliases."""
    return ['sudo', '--', *aliases.eval_alias(args)]

aliases['install'] = "apt install cowsay"
xsudo install
# Password:
# Install cowsay

@aliases.register
@aliases.return_command
def _vi(args):
    """Universal vi editor."""
    if $(which vim 2>/dev/null):
        return ['vim'] + args
    else:
        return ['vi'] + args

vi /etc/hosts

Note! Using alias that returns command is much more preferable than callable alias if you need to just change the command. Callable alias is a complex process wrapper and in case of choice between return command alias and callable alias the right choice is the first one.

Callable aliases

def _myargs1(args):
#def _myargs2(args, stdin=None):
#def _myargs3(args, stdin=None, stdout=None):
#def _myargs4(args, stdin=None, stdout=None, stderr=None):
#def _myargs5(args, stdin=None, stdout=None, stderr=None, spec=None):
#def _myargs6(args, stdin=None, stdout=None, stderr=None, spec=None, stack=None):
    print(args)
    # print(args, file=stdout)  # Using stdout directly is the best practice to support pipes/tests/future.
    
aliases['args'] = _myargs1
del _myargs1

args 1 2 3
#['1', '2', '3']

Simple definition with decorator:

@aliases.register
def _hello():
    echo world
    
hello
# world

Read stdin and write to stdout (real-life example - xontrib-pipeliner):

# Add an exclamation point to each line
def _exc(args, stdin, stdout):
    for line in stdin.readlines():
        print(line.strip() + '!', file=stdout, flush=True)

aliases['exc'] = _exc

echo hello | exc
# hello!

# JSON to YAML
@aliases.register("j2y")
def __j2y(args, stdin, stdout):
    import json, yaml
    print(yaml.dump(json.loads(stdin.read())), file=stdout)

# YAML to JSON
@aliases.register("y2j")
def __y2j(args, stdin, stdout):
    import yaml, json
    json.dump(yaml.safe_load(stdin), stdout, indent=4)

echo '{"hello":{"world":"42"}}' | j2y
# hello:
#   world: 42

echo 'hello:\n  world: 42' | y2j
# {
#     "hello": {
#         "world": "42"
#     }
# }

Capturing:

Callable aliases tend to be capturable. Only the explicitly denoted uncaptured subprocess operator $[] is uncapturable, and the subprocess's stdout passes directly through xonsh to the screen.

@aliases.register
def _hunter():
    print('catch me')
    echo if
    $[echo you]
    ![echo can]
hunter
# catch me
# if
# you
# can
$(hunter)
# you
# 'catch me\nif\ncan\n'

Calambur! The "callable alias" could be shortanized to "callias". The name Callias is primarily a gender-neutral name of Greek origin that means Beauty.

Decorator Alias

Using DecoratorAlias and callable output_format you can create transformer:

from xonsh.procs.specs import SpecAttrDecoratorAlias as dalias  # xonsh >= 0.18.0

imp = type('ImpCl', (object,), {'__getattr__':lambda self, name: __import__(name) })()

aliases['@noerr'] = dalias({"raise_subproc_error": False},
                            "Set `raise_subproc_error` to False.")
aliases['@lines'] = dalias({"output_format": 'list_lines'},
                            "Set `list_lines` output format.")
aliases['@json'] = dalias({"output_format": lambda lines: imp.json.loads('\n'.join(lines))},
                           "Set `json` output format.")
aliases['@path'] = dalias({"output_format": lambda lines: imp.pathlib.Path(':'.join(lines))},
                           "Set `path` output format.")
aliases['@yaml'] = dalias({"output_format": lambda lines: imp.yaml.safe_load('\n'.join(lines))},
                           "Set `yaml` output format.")

Now you can:

$(@lines ls /)
# ['/bin', '/etc', '/home']

$(@json echo '{"a":1}')  # Try with `curl` ;)
# dict({"a":1})

$(@path which xonsh)
# Path('/path/to/xonsh')

$(@path which xonsh).parent
# Path('/path/to')


aliases['ydig'] = '@yaml dig +yaml'  # Update `dig` via `brew install bind` to have `+yaml`.
y = $(ydig google.com)
y[0]['type']
# 'MESSAGE'


$RAISE_SUBPROC_ERROR = True
if ![@noerr ls nononofile]:  # Do not raise exception in case of error.
    echo file

Abbrevs

There is xontrib-abbrevs as an alternative to aliases. You can create abbrev and set the position of editing:

xpip install xontrib-abbrevs
xontrib load abbrevs

abbrevs['gst'] = 'git status'
gst  # Once you hit <space> or <return> 'gst' gets expanded to 'git status'.

abbrevs['gp'] = "git push <edit> --force"  # Set the edit position.
abbrevs['@'] = "@(<edit>)"  # Make shortcut.
abbrevs['...'] = "cd ../.."  # Workaround for syntax intersections with Python i.e. `elepsis` object from Python here.

# You can set a callback that receives the current command buffer and the word that triggered abbrev
abbrevs['*'] = lambda buffer, word: "asterisk" if buffer.text.startswith('echo') else word
ls *  # will stay
echo *  # will be transformed to `echo asterisk`

Path strings

The p-string returns Path object:

path = p'~/.xonshrc'
path
# Path('/home/snail/.xonshrc')

[path.name, path.exists(), path.parent]
# ['.xonshrc', True, Path('/home/snail')]

[f for f in path.parent.glob('*') if 'xonsh' in f.name]
# [Path('/home/snail/.xonshrc')]

dir1 = 'hello'
dir2 = 'world'
path = p'/tmp' / dir1 / dir2 / 'from/dir' / f'{dir1}'
path
# Path('/tmp/hello/world/from/dir/hello')

The best description of how string literlas is working is in the table from tutorial.

A simple way to read and write the file content using Path string:

text_len = p'/tmp/hello'.write_text('Hello world')
content = p'/tmp/hello'.read_text()
content
# 'Hello world'

Globbing - get the list of files from path by mask or regexp

To Normal globbing add g before back quotes:

ls *.*
ls g`*.*`

for f in gp`/tmp/*.*`:  # `p` is to return path objects
    print(f.name)
      
for f in gp`/tmp/*/**`:  # `**` is to glob subdirectories
    print(f)

To Regular Expression Globbing add r before back quotes:

ls `.*`
ls r`.*`

for f in rp`.*`:          # `p` is to return path instances
      print(f.exists())

To Custom function globbing add @ and the function name before back quotes:

def foo(s):
    return [i for i in os.listdir('.') if i.startswith(s)]
cd /
@foo`bi`
#['bin']

Macros

Simple macros

def m(x : str):
    return x

# No macro calls:
[m('me'), m(42), m(m)]
# ['me', 42, <function __main__.m>]

# Macro calls:
[m!('me'), m!(42), m!(identity), m!(42), m!(  42 ), m!(import os)]
# ["'me'", '42', 'identity', '42', '42', 'import os']

m!(if True:
    pass)
# 'if True:\n    pass'

Real life example:

from_json = lambda cmd: __import__("json").loads(evalx(f"$({cmd})"))
o = from_json!(echo '{"a":1}')
o
#{'a': 1}
type(o)
# dict

Subprocess Macros

echo! "Hello!"
# "Hello!"

bash -c! echo "Hello!"
# Hello!

podman run -it --rm xonsh/xonsh:slim xonsh -c! 2+2
# 4

Inside of a macro, all additional munging is turned off:

echo $USER
# lou

echo! $USER
# $USER

Macro block

Builtin macro Block

from xonsh.contexts import Block
with! Block() as b:
    qwe
    asd
    zxc

b.macro_block
# 'qwe\nasd\nzxc\n\n'
b.lines
# ['qwe', 'asd', 'zxc', '']

Custom JSON block

import json

class JsonBlock:
    __xonsh_block__ = str

    def __enter__(self):
        return json.loads(self.macro_block)

    def __exit__(self, *exc):
        del self.macro_block, self.macro_globals, self.macro_locals


with! JsonBlock() as j:
    {
        "Hello": "world!"
    }
    
j['Hello']
# world!

Custom Podman block

The example is from xontrib-macro-lib:

from xonsh.contexts import Block

class Container(Block):
    """Run xonsh codeblock in a container."""

    def __init__(self):
       self.image = 'xonsh/xonsh:slim'

    def __exit__(self, *a, **kw):
        $[podman run -it --rm @(self.image) /usr/local/bin/xonsh -c @(self.macro_block)]


with! Container() as d:
   pip install lolcat
   echo "We're in the container now!" | lolcat

Macro blocks library

Tab-Completion

completer list  # List the active completers

Take a look into xontrib-fish-completer - it provides more rich completion than default bash completer.

Create your own completer:

def dummy_completer(prefix, line, begidx, endidx, ctx):
    '''
    Completes everything with options "lou" and "carcolh",
    regardless of the value of prefix.
    '''
    return {"lou", "carcolh"}
    
completer add dummy dummy_completer  # Add completer: `completer add <NAME> <FUNC>`
# Now press Tab key and you'll get {"lou", "carcolh"} in completions
completer remove dummy

Bind hotkeys in prompt toolkit shell

Uncover the power of prompt_toolkit by binding the hotkeys. Run this snippet or add it to ~/.xonshrc:

from prompt_toolkit.keys import Keys

@events.on_ptk_create
def custom_keybindings(bindings, **kw):

    # Press F1 and get the list of files
    @bindings.add(Keys.F1)  # or for Mac try `@bindings.add("c-k")  # control+k`
    def run_ls(event):
        ls -l
        event.cli.renderer.erase()
    
    # Press F3 to insert the grep command
    @bindings.add(Keys.F3)  # or for Mac try `@bindings.add("c-k")  # control+k`
    def add_grep(event):
        event.current_buffer.insert_text('| grep -i ')

    # Clear line by pressing `Escape` key
    @bindings.add("escape")
    def clear_line(event):
        event.current_buffer.delete_before_cursor(1000)

Xontrib - extension or plugin for xonsh

Xontrib lists:

Github topic
Github repositories
awesome-xontribs

To install xontribs xonsh has xpip - a predefined alias pointing to the pip command associated with the Python executable running this xonsh. Using xpip is the right way to install xontrib to be confident that the xontrib will be installed in the right environment.

If you want to create your own xontrib using xontrib-template is the best way:

xpip install copier jinja2-time cookiecutter
copier copy --trust gh:xonsh/xontrib-template .

Xontrib as a bridge

You can integrate python tools into xonsh context and environment using xontrib e.g. see fstrider xontrib where xontrib allows to inject xonsh context into file system navigation tool.

Xonsh Script (xsh)

Real-life example of xsh script that has: arguments, tab completion for arguments (using xontrib-argcomplete), subprocess calls with checking the result, colorizing the result and exit code:

#!/usr/bin/env xonsh
# PYTHON_ARGCOMPLETE_OK                                  
import argparse
import argcomplete  # Tab completion support with xontrib-argcomplete
from argcomplete.completers import ChoicesCompleter

$RAISE_SUBPROC_ERROR = True  # Raise an error if a subprocess returns a non-zero exit status.
                             # Read more: https://xon.sh/envvars.html#raise-subproc-error

argp = argparse.ArgumentParser(description=f"Get count of lines in HTML by site address.")
argp.add_argument('--host', required=True, help="Host").completer=ChoicesCompleter(('xon.sh', 'github.com'))
argcomplete.autocomplete(argp)
args = argp.parse_args()

if result := !(curl -s -L @(args.host)):  # Python + Subprocess = ♥
    lines_count = len(result.out.splitlines())
    printx(f'{{GREEN}}Count of lines on {{#00FF00}}{args.host}{{GREEN}}: {{YELLOW}}{lines_count}{{RESET}}')
else:
    printx(f'{{RED}}Error while reading {{YELLOW}}{args.host}{{RED}}! {{RESET}}') # Colorizing messages
    exit(1)  # Exit with code number 1

Try it in action:

xonsh
pip install argcomplete xontrib-argcomplete
xontrib load argcomplete
cd /tmp
wget https://raw.githubusercontent.com/anki-code/xonsh-cheatsheet/main/examples/host_lines.xsh
chmod +x host_lines.xsh
./host_lines.xsh --ho<Tab>
./host_lines.xsh --host <Tab>
./host_lines.xsh --host xon.sh
# Count of lines on xon.sh: 568

To make the interaction with scripts more awesome see also xonsh-awesome-cli-app and articles around click, rich, typer, etc.

How to get the script path

Get the script path from $ARGS[0]:

echo @("""echo This script is in @(pf"{$ARGS[0]}".parent)""") > /tmp/getpath.xsh
chmod +x /tmp/getpath.xsh
/tmp/getpath.xsh
# This script is in /tmp

Unit tests with xonsh and pytest

Start here: How do I write unit tests?.

History

There are two history backends: json and sqlite which xonsh has by default. The json backend creates a json file with commands history on every xonsh session. The sqlite backend has one file with SQL-database.

We recommend using the sqlite backend because it saves the command on every execution, and querying the history using SQL is very handy, i.e. history-search, history-pull.

echo 123
# 123

__xonsh__.history[-1]
# HistoryEntry(cmd='echo 123', out='123\n', rtn=0, ts=[1614527550.2158427, 1614527550.2382812])

history info
# backend: sqlite
# sessionid: 637e577c-e5c3-4115-a3fd-99026f113464
# filename: /home/user/.local/share/xonsh/xonsh-history.sqlite
# session items: 2
# all items: 8533
# gc options: (100000, 'commands')

sqlite3 $XONSH_HISTORY_FILE  "SELECT inp FROM xonsh_history ORDER BY tsb LIMIT 1;"
# echo 123

aliases['history-search'] = """sqlite3 $XONSH_HISTORY_FILE @("SELECT inp FROM xonsh_history WHERE inp LIKE '%" + $arg0 + "%' AND inp NOT LIKE 'history-%' ORDER BY tsb DESC LIMIT 10");"""
cd /tmp
history-search "cd /"
# cd /tmp
history-search! cd /  # macro call
# cd /tmp

pip install sqlite_web
sqlite_web $XONSH_HISTORY_FILE  # Open the database in the browser

history pull  # Pull the history from parallel sessions and add to the current session. [xonsh -V > 0.13.4]

There is a third-party history backend that's supplied in xontribs: xontrib-history-encrypt.

Interactive mode events

When you're in xonsh interactive mode you can register an event, i.e.:

@events.on_chdir
def mychdir(olddir, newdir, **kw):
    echo Jump from @(olddir) to @(newdir)
    
cd /tmp
# Jump from /home/snail to /tmp

Help

Add ? (regular help) or ?? (super help) to the command:

ls?
# man page for ls

import json
json?
# json module help
json??
# json module super help

Known issues and workarounds

ModuleNotFoundError

Sometimes when you're using PyPi, Conda, or virtual environments you can forget about the current version and location of Python and try to import packages in xonsh resulting in a ModuleNotFoundError error. Often this means you installed the package in another environment and didn't realise it. To avoid this read the section about xonsh installation above.

Shadowing of console tools or shell syntax with Python builtins

In case of name or syntax collision try to use aliases or abbrevs to resolve the conflict.

The case with id or zip:

id
# <function id>
ID
# uid=501(user) gid=20(staff) groups=20(staff) ...
zip
# zip builtin
ZIP
# zip [-options] [-b path] ...
Zip
# zip [-options] [-b path] ...

The case with ellipsis:

aliases['...'] = 'cd ../..'  # looks nice, but
...
# Elepsis

del aliases['...']
abbrevs['...'] = 'cd ../..'
...  # becomes `cd ../..`

The case with import:

cd /tmp
$PATH.append('/tmp')
echo 'echo I am import' > import && chmod +x import

import  # Run subprocess `./import`
# I am import

import args  # Run Python import of `args` module
# ModuleNotFoundError: No module named 'args'

aliases['imp'] = "import"
imp
# I am import

Uncaptured output

If you want to capture the output from a tool that basically interactive but has captured mode. For example basically ssh return the remote terminal that should be unthredable and uncapturable. But if you use it for getting the data from remote host you would like to capture it. There are three workarounds:

!(@thread ssh host -T "echo 1")  # Switch to thread (xonsh >= 0.18.3).
#CommandPipeline(returncode=0, output='1\n')

!(echo 123 | head)  # stream to captured
#CommandPipeline(returncode=0, output='123\n')

!(bash -c "echo 123")  # wrap to capturable tool
#CommandPipeline(returncode=0, output='123\n')

Frozen terminal in interactive tools

If you run a console tool and get a frozen terminal (Ctrl+c, Ctrl+d is not working), this can be that the tool was interpreted as a threaded and capturable program but the tool actually has interactive elements that expect input from the user. There are bunch of workarounds:

@unthread ./tool.sh  # xonsh >= 0.18.3

with ${...}.swap(THREAD_SUBPROCS=False):
      ./tool.sh

$[./tool.sh]

New python version

Because of xonsh syntax was based on Python syntax you can face with parser issues if you install the new Python version and run xonsh. Check that you're specifying certain version of Python when you're using xonsh in your projects and there is no situation when python can be updated witout testing.

Tips and tricks

Make your own installable xonsh RC file

Start by forking xontrib-rc-awesome.

Inline import

Use __xonsh__.imp as inline importer (xonsh >= 0.18.2):

__xonsh__.imp.json.loads('{"a":1}')
# {'a': 1}
__xonsh__.imp.datetime.datetime.now().isoformat()
# '2024-02-12T15:29:57.125696'
__xonsh__.imp.hashlib.md5(b'Hello world').hexdigest()
# '3e25960a79dbc69b674cd4ec67a72c62'

Triple quotes

To avoid escape characters (i.e. echo "\"hello\"") and make strings more elegant use triple quotes:

echo """{"hello":'world'}"""
# {"hello":'world'}

Python walrus operator in action

Use in subprocess:

echo Hello @(_name := input('Name: '))  # Use `_` to keep env clean.
echo Hello again @(_name)
# Name: Mike
# Hello Mike
# Hello again Mike

Use with commands:

(servers := $(@json echo '["srv1", "srv2"]'))
# list(['srv1', 'srv2'])
echo @(servers[0])
# srv1

Jump from aliases to CLI apps

If you realize that your alias becomes the app it's time to look at xonsh-awesome-cli-app.

Make interruption tolerant transactions

When you have group of commands (transaction) it's good to use DisableInterrupt from xontrib-macro:

from xontrib.macro.signal import DisableInterrupt

echo start
with! DisableInterrupt():
    echo 'sleep start'
    sleep 10
    echo 'sleep end'
echo finish

# start
# sleep start
# [Press Ctrl+C]
# KeyboardInterrupt will be raised at the end of current transaction.
# sleep end
# Exception KeyboardInterrupt: KeyboardInterrupt was received during transaction.

Using a text block in the command line

The first way is to use multiline strings:

echo @("""
line 1
line 2
line 3
""".strip()) > file.txt

$(cat file.txt)
# 'line 1\nline 2\nline 3\n'

The second way is to use xonsh macro block via xontrib-macro:

xpip install xontrib-macro

from xontrib.macro.data import Write

with! Write('/tmp/t/hello.xsh', chmod=0o700, replace=True, makedir=True, verbose=True):
    echo world
    
/tmp/t/hello.xsh
# world

Run commands in a container:

podman run -it --rm xonsh/xonsh:slim xonsh -c @("""
pip install --disable-pip-version-check -q lolcat
echo "We're in the podman container now!" | lolcat
""")

Don't forget that Alt+Enter can run the command from any place where the cursor is.

Use `prompt` instead of `input` for multiline input

In python there is input function but it has no support of multiline pasting. Use prompt:

from prompt_toolkit import prompt

echo @(prompt('Content:\n')) > /tmp/myfile
# Content:
# <Paste multiline text "1\n\2\n" from clipboard>

cat /tmp/myfile
# 1
# 2

One line version using inline importer (__xonsh__.imp):

echo @(__xonsh__.imp.prompt_toolkit.prompt("Content:\n")) > /tmp/myfile

Using the name of the alias in alias logic

@aliases.register(",")
@aliases.register(",,")
@aliases.register(",,,")
@aliases.register(",,,,")
def _superdot():
    cd @("../" * len($__ALIAS_NAME))
    
,    # cd ../
,,   # cd ../../
,,,  # cd ../../../

Transparent callable environment variables

For example, you want to have the current timestamp in every command but instead of nesting like @(dt()) you want sugar:

class TimestampCl:
    def __repr__(self):
        from datetime import datetime
        return str(datetime.now().isoformat())

$dt = TimestampCl()

echo $dt
sleep 1
echo $dt
# 2024-03-05T23:34:50.188014
# 2024-03-05T23:34:51.259861

If you want more sugar use imp from the previous trick:

imp = type('ImpCl', (object,), {'__getattr__':lambda self, name: __import__(name) })()
$dt = type('TimeCl', (object,), {'__repr__':lambda self: str(imp.datetime.datetime.now().isoformat()) })()

echo $dt
sleep 1
echo $dt
# 2024-03-05T23:34:50.188014
# 2024-03-05T23:34:51.259861

Ask to input argument and with autocomplete

Ask simple input:

echo @(input('Text: '))
# Text: hello
# hello

echo Hello @(_name := input('Name: '))  # Use `_` to keep env clean.
echo Hello again @(_name)
# Name: Mike
# Hello Mike
# Hello again Mike

$ENV_NAME = input('Name: ')  # Use input to set and reuse env variable
echo Name is $ENV_NAME
# Name: Alex
# Name is Alex

# The way to have continuous interactive search.
while 1: ![cat /etc/passwd | grep --color -i @(input('\nUsername: '))]
while 1: ![cat @(f:='/etc/passwd') | grep --color -i @(input(f+': '))]  # walrus happy

Ask for input with completion and history:

from prompt_toolkit import PromptSession
from prompt_toolkit.completion import WordCompleter
from prompt_toolkit.history import FileHistory

def ask(title : str, completions : list = []):
    filename = ''.join(c for c in title if c.isalpha())
    history = FileHistory($XONSH_DATA_DIR + f'/ask_{filename}.txt')
    completer = WordCompleter(completions)
    session = PromptSession(completer=completer, history=history)
    user_input = session.prompt(f'{title}: ')
    return user_input


echo I am saying @(ask('What to say'))
# What to say: hello
# I am saying hello

echo Give @(ask('Fruit', ['apple', 'banana', 'orange'])) to @(ask('To', [$(whoami).strip()]))
# Fruit: <Tab>
# Fruit: apple
# To: <Tab>
# To: user
# Give apple to user

$MY_DIR = ask('Dir', $(ls /).splitlines())
# Dir: <Tab>

From the shell to REST API for one step

If you want to run shell commands from REST API you can create a flask wrapper using xontrib-macro:

xpip install flask xontrib-macro

cd /tmp

from xontrib.macro.data import Write
with! Write('myapi.xsh', chmod=0o700):
    import json
    from flask import Flask, request
    app = Flask(__name__)
    @app.route('/echo', methods=['GET'])
    def index():
        say = request.args.get('say')
        result = $(echo -n @(say))  # run subprocess command
        return json.dumps({'result': result})
    app.run(host="127.0.0.1", port=5000)  # debug=True

./myapi.xsh
# Running on https://127.0.0.1:5000

curl 'https://127.0.0.1:5000/echo?say=cow'
# {"result": "cow"}

Don't forget about API security.

Run pure xonsh engine

Basically xonsh session loads RC files, inherit environment, uses dynamic colors, git callbacks in prompt, saves commands to history and more. Most of this features are disabled in not interactive mode (xonsh -c 'echo 1'). But in some cases you can want to rid of all features to reduce overhead on running completely. Here is the path:

xonsh --no-rc --no-env -DCOLOR_INPUT=0 -DCOLOR_RESULTS=0 -DPROMPT='@ ' \
      -DXONSH_HISTORY_BACKEND=dummy -DXONTRIBS_AUTOLOAD_DISABLED=1 -st rl

Here:

--no-rc to prevent loading RC files.
--no-env to prevent inheriting the environment.
-DCOLOR_INPUT=0 to disable colors and file completer that can read files to choose the right color.
-DCOLOR_RESULTS=0 to disable colors in output.
-DPROMPT='@ ' to disable prompt with gitstatus and other complex fields.
-DXONSH_HISTORY_BACKEND=dummy to disable history backend.
-DXONTRIBS_AUTOLOAD_DISABLED=1 to avoid loading xontribs.
-st rl to use cheapest shell backend (readline).

Interactively debugging a script

If you want to have a breakpoint to debug a script, use the standard Python pdb:

xpip install xontrib-macro
from xontrib.macro.data import Write
with! Write('/tmp/run.xsh', chmod=0o700, replace=True, makedir=True):
    echo hello
    $VAR = 1
    var = 2

    import pdb
    pdb.set_trace()   # interactive debug

    echo finish


xonsh /tmp/run.xsh
# hello
# > /tmp/run.xsh(9)<module>()
# -> echo finish
# (Pdb)

var
# 2

__xonsh__.env['VAR']
# 1

exit
# bdb.BdbQuit

Using xonsh wherever you go through the SSH

You've stuffed your command shell with aliases, tools, and colors but you lose it all when using ssh. The mission of the xxh project is to bring your favorite shell wherever you go through ssh without root access or system installations.

How to modify a command before execution?

To change the command between pressing enter and execution there is the on_transform_command event:

xpip install lolcat

@events.on_transform_command
def _(cmd, **kw):
    if cmd.startswith('echo') and 'lolcat' not in cmd:  
        # Be careful with the condition! The modified command will be passed 
        # to `on_transform_command` event again and again until the event 
        # returns the same command. Newbies can make a mistake here and
        # end up with unintended looping.
        return cmd.rstrip() + ' | lolcat'
    else:
        return cmd
        
echo 123456789 # <Enter>
# Execution: echo 123456789 | lolcat

Comma separated thousands in output (custom formatter)

Here is a snippet from @maxwellfire:

50000+50000
# 100000

500+500.123
# 1000.123

import xonsh.pretty
xonsh.pretty.for_type(type(1), lambda int, printer, cycle: printer.text(f'{int:,}'))
xonsh.pretty.for_type(type(1.0), lambda float, printer, cycle: printer.text(f'{float:,}'))

50000+50000
# 100,000

500+500.123
# 1,000.123

Builtin `chdir` context manager for scripting

from xonsh.tools import chdir

cd /tmp
mkdir -p dir1

pwd
with chdir("./dir1"):
    pwd
pwd

# /tmp
# /tmp/dir1
# /tmp

Juggling of exit code using python substitution

cd into a directory and, if the count of files is less then 100, run ls:

aliases['cdls'] = "cd @($arg0) && @(lambda: 1 if len(g`./*`) > 100 else 0) && ls"
cdls / && pwd
# bin dev etc ...
# /
cdls /usr/sbin && pwd
# /usr/sbin

How to paste and edit multiple lines of code while in interactive mode

In some terminals (Konsole in Linux or Windows Terminal for WSL) you can press ctrl-x ctrl-e to open up an editor (nano in Linux) in the terminal session, paste the code there, edit and then quit out. Your multiple-line code will be pasted and executed.

Waiting for the job done

sleep 100 &  # job 1
sleep 100 &  # job 2
sleep 100 &  # job 3

while $(jobs):
    time.sleep(1)

print('Job done!')

Do asynchronous task in interactive prompt

For example you can continuously pulling history from other sessions or just run this in xonsh to print every second:

$SHELL_TYPE
# 'prompt_toolkit'

import asyncio
from prompt_toolkit.shortcuts import print_formatted_text

async def print_and_sleep():
    while True:
        print_formatted_text('hey!')        
        await asyncio.sleep(2)

loop = asyncio.get_event_loop()
loop.create_task(print_and_sleep())

How to trace xonsh code?

Trace with hunter:

pip install hunter
$PYTHONHUNTER='depth_lt=10,stdlib=False' $XONSH_DEBUG=1 xonsh -c 'echo 1'

Or try xunter for tracing and profiling.

From Bash to Xonsh

Read Bash to Xonsh Translation Guide, run bash -c! echo 123 or install xontrib-sh.

Xonsh and Windows

First of all we recommend using WSL 2 with Manjaro (that maintains a rolling release) on Windows. Don't forget to fix PATH.

But if you want to use xonsh in a Windows environment:

Install Windows Terminal - the modern terminal emulator for Windows.
Install xontrib coreutils, cmdix, pycoreutils - a pure Python implementation of the UNIX coreutils i.e. echo, cat, pwd,ls, etc.
Read Windows-specific tips and tricks.

Recipes

Using many profiles with AWS CLI and xonsh aliases

aws configure --profile p1
aws configure --profile p2

aliases['aws-p1'] = "$AWS_DEFAULT_PROFILE='p1' @('aws') @($args)"
aliases['aws-p2'] = "$AWS_DEFAULT_PROFILE='p2' @('aws') @($args)"

aws-p2 s3 ls s3://my-profile1-bucket/  # The same as `aws s3 ls --profile p2 s3://my-profile1-bucket/`

Answers to the holy war questions

Bash is everywhere! Why xonsh?

Python is everywhere as well ;)

Xonsh is slower! Why xonsh?

You can spend significantly more time Googling and debugging sh-based solutions as well as significantly more time to make the payload work after running a command. Yeah, xonsh is a bit slower but you will not notice that in real-life tasks :)

Also, take a look:

Python 3.12: A Game-Changer in Performance and Efficiency
Python 3.11 is up to 10-60% faster than Python 3.10
Making Python 5x FASTER with Guido van Rossum.
RustPython (performance of Ruff - Python linter on Rust)
xonsh parser on Rust
Nuitka the Python Compiler (xonsh-binary)
uv and mamba to install packages as fast as possible.

My fancy prompt in another shell is super duper! Why xonsh?

The fancy prompt is the tip of the iceberg. Xonsh shell brings other important features to love: sane language, powerful aliases, agile extensions, history backends, fully customisable tab completion, magic macro blocks, behaviour customisation via environment variables, and more, and more, and more :)

Xonsh has issues! Why xonsh?

Compared to 15-20-year-old shells, yeah, xonsh is a 5-year-old youngster. But we've used it over these 5 years day by day to solve our tasks with success and happiness :)

Become a xonsh developer and contributor

Moved to xonsh-developer-toolkit.

Thank you!

Thank you for reading! This cheatsheet is just the tip of the iceberg of the xonsh shell; you can find more in the official documentation.

Also you can install the cheatsheet xontrib:

xpip install xontrib-cheatsheet
xontrib load cheatsheet
cheatsheet
# Opening: https://github.com/anki-code/xonsh-cheatsheet/blob/main/README.md

If you like the cheatsheet, click ⭐ on the repo and tweet.

Credits

Xonsh Tutorial
Most copy-pastable examples prepared by xontrib-hist-format
The cheat sheet xontrib was created with xontrib template.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Uh oh!