Windows Guide¶
Installation¶
The easy way¶
The easiest way to install xonsh on windows is through the Anaconda Python Distribution and the conda package manager.
Note
Xonsh is not supported on legacy Python (2.7).
Install xonsh with the following command:
> conda config --add channels conda-forge
> conda install xonsh
This will install xonsh and all the recommended dependencies. Next, run xonsh:
> xonsh
snail@home ~ $
Install from source¶
To install xonsh from source on Windows, first install Python v3.4+ from http://python.org. Remember to select “Add python to PATH” during installation.
Next, install the prompt_toolkit dependency via pip
:
> pip install prompt-toolkit
Download the latest xonsh-master.zip from github and unzip it
to xonsh-master
.
Now install xonsh:
> cd xonsh-master
> python setup.py install
Next, run xonsh:
> xonsh
snail@home ~ $
Usage¶
Color style¶
The dark red and blue colors are completely unreadable in Windows’ default terminal.

There are ways to configure the colors (see below), but to give new users the
best experience Xonsh has some tricks to fix colors. This is controlled by the
$INTENSIFY_COLORS_ON_WIN
environment variable which is True
by default.
On Windows 10
Windows 10 supports true color in the terminal, so on Win 10 Xonsh will use a style with hard coded colors instead of the terminal colors.

On older Windows
On older windows installations Xonsh takes an other approach and replaces some of the unreadable dark colors with more readable alternatives (e.g. blue becomes cyan).
Configure the terminal colors
It is possible to configure the Windows console with readable default colors, but it is tedious to do manually. The Microsoft console team has made a handy tool to configure colors in the terminal
- Download Colortool from from GitHub
With better colors configured, $INTENSIFY_COLORS_ON_WIN
should be set to
False
to allow the console to control the colors.
You can do this by adding the following to the xonsh run control file .xonshrc
:
$INTENSIFY_COLORS_ON_WIN = False
Avoid locking the working directory¶
Python (like other processes on Windows) locks the current working directory so
it can’t be deleted or renamed. cmd.exe
has this behaviour as well, but it
is quite annoying for a shell.
The free_cwd xontrib (add-on) for xonsh solves some of this problem. It works by hooking the prompt to reset the current working directory to the root drive folder whenever the shell is idle. It only works with the prompt-toolkit back-end. To enable that behaviour run the following:
Add this line to your ~/.xonshrc
file to have it always enabled.
>>> xontrib load free_cwd
Name space conflicts¶
Due to ambiguity with the Python dir
builtin, to list the current directory
via the cmd.exe
builtin you must explicitly request the .
, like this:
>>> dir .
Volume in drive C is Windows
Volume Serial Number is 30E8-8B86
Directory of C:\Users\snail\xonsh
2015-05-12 03:04 <DIR> .
2015-05-12 03:04 <DIR> ..
2015-05-01 01:31 <DIR> xonsh
0 File(s) 0 bytes
3 Dir(s) 11,008,000,000 bytes free
Many people create a d
alias for the dir
command to save
typing and avoid the ambiguity altogether:
>>> aliases['d'] = ['cmd', '/c', 'dir']
You can add aliases to your ~/.xonshrc
to have it always
available when xonsh starts.
Unicode support for Windows¶
Python’s utf-8 unicode is not compatible with the default shell ‘cmd.exe’ on Windows. The package win_unicode_console
fixes this. Xonsh will use win_unicode_console
if it is installed. This can be disabled/enabled with the $WIN_UNICODE_CONSOLE environment variable.
Note
Even with unicode support enabled the symbols available will depend on the font used in cmd.exe.
The packages win_unicode_console
can be installed along with xonsh by using the package name xonsh[win]
or separately using pip or conda.
> pip install win_unicode_console
> conda install --channel xonsh win_unicode_console