Updating and customizing xonsh¶

Updating xonsh¶

How to update xonsh depend on the install method.

xonsh installed via pip

If you have installed via pip (possibly into a virtual environment), then you can update xonsh from within itself with the following command:

@ xpip install --upgrade xonsh

xpip (note the “x” at the beginning of xpip) is a predefined alias pointing to the pip command associated with the Python executable running this xonsh.

xonsh installed via a package manager

If you have installed via a package manager, it is recommended to update xonsh through the package manager’s appropriate command. For example, on macOS if you have installed via homebrew, you should update like this:

$ brew upgrade xonsh

Customizing xonsh - How do I…¶

…change the current color theme?¶

You can view the available styles by typing

@ xonfig styles

For a quick peek at the theme’s colors you can do

@ xonfig colors <theme name>

To set a new theme, do

@ $XONSH_COLOR_STYLE='<theme name>'

Registering custom styles¶

If you aren’t happy with the styles provided by us (and pygments), you can create and register custom styles.

To do so, add something similar to your .xonshrc:

from xonsh.tools import register_custom_style
mystyle = {
    "Literal.String.Single": "#ff88aa",
    "Literal.String.Double": "#ff4488",
    "RED": "#008800",
}
register_custom_style("mystyle", mystyle, base="monokai")
$XONSH_COLOR_STYLE="mystyle"

You can check xonfig colors for the token names. The base style will be used as a fallback for styles you don’t set - pick one from xonfig styles (default is used if omitted).

…import python modules from a local directory?¶

The modules available for import in a given xonsh session depend on what’s available in sys.path. If you want to be able to import a module that resides in the current directory, ensure that there is an empty string as the first element of your sys.path

@ import sys
@ sys.path.insert(0, '')

…set `xonsh` as my default shell?¶

If you want to use xonsh as your default shell, you will first have to add xonsh to /etc/shells.

First ensure that xonsh is on your $PATH

$ which xonsh

Then, as root, add xonsh to the shell list

# which xonsh >> /etc/shells

To change shells, run

$ chsh -s $(which xonsh)

You will have to log out and log back in before the changes take effect.

…select a tab completion result without executing the current line?¶

In the prompt_toolkit shell, you can cycle through possible tab-completion results using the TAB key and use ENTER to select the completion you want. By default, ENTER will also execute the current line. If you would prefer to not automatically execute the line (say, if you’re constructing a long pathname), you can set

$COMPLETIONS_CONFIRM=True

in your xonshrc

…add a default argument to a builtin `xonsh` alias?¶

If you want to add a default argument to a builtin alias like dirs the standard alias definition method will fail. In order to handle this case you can use the following solution in your xonshrc:

from xonsh.dirstack import dirs

def _verbose_dirs(args, stdin=None):
    return dirs(['-v'] + args, stdin=stdin)

aliases['dirs'] = _verbose_dirs

…make terminal tabs start in the correct directory?¶

If you use Gnome Terminal or another VTE terminal and it doesn’t start new tabs in the CWD of the original TAB, this is because of a custom VTE interface. To fix this, please add {vte_new_tab_cwd} somewhere to you prompt:

$PROMPT = '{vte_new_tab_cwd}' + $PROMPT

This will issue the proper escape sequence to the terminal without otherwise affecting the displayed prompt.

…set up the “Open Terminal Here” action in Thunar?¶

If you use Thunar and “Open Terminal Here” action does not work, you can try to replace a command for this action by the following:

exo-open --working-directory %f --launch TerminalEmulator xonsh --shell-type=best

In order to do this, go to Edit > Configure custom actions..., then choose Open Terminal Here and click on Edit currently selected action button.

…use utf-8 characters in xonsh?¶

If you are unable to use utf-8 (ie. non-ascii) characters in xonsh. For example if you get the following output

@ echo "ßðđ"
xonsh: For full traceback set: $XONSH_SHOW_TRACEBACK = True
UnicodeEncodeError: 'ascii' codec can't encode characters in position 0-2: ordinal not in range(128)

The problem might be:

Your locale is not set to utf-8, to check this you can set the content of the environment variable LC_TYPE
Your locale is correctly set but after xonsh started. This is typically the case if you set your LC_TYPE inside your xonshrc and xonsh is your default/login shell. To fix this you should see the documentation of your operating system to know how to correctly setup environment variables before the shell start (~/.pam_environment for example)

…fix a `libgcc_s.so.1` error?¶

On certain flavors of Linux you may periodically encounter this error message when starting xonsh:

libgcc_s.so.1 must be installed for pthread_cancel to work
Aborted (core dumped)

This is due to an upstream Python problem and can be fixed by setting LD_PRELOAD:

$ env LD_PRELOAD=libgcc_s.so.1 xonsh

…color my man pages?¶

You can add add man page color support using less environment variables:

# Coloured man page support
# using 'less' env vars (format is '\E[<brightness>;<colour>m')
$LESS_TERMCAP_mb = "\033[01;31m"     # begin blinking
$LESS_TERMCAP_md = "\033[01;31m"     # begin bold
$LESS_TERMCAP_me = "\033[0m"         # end mode
$LESS_TERMCAP_so = "\033[01;44;36m"  # begin standout-mode (bottom of screen)
$LESS_TERMCAP_se = "\033[0m"         # end standout-mode
$LESS_TERMCAP_us = "\033[00;36m"     # begin underline
$LESS_TERMCAP_ue = "\033[0m"         # end underline

…use xonsh inside Emacs?¶

see emacs.