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.