Windows Guide


The easy way

The easiest way to install xonsh on windows is through the Anaconda Python Distribution and the conda package manager.


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 Remember to select “Add python to PATH” during installation.

Next, install the prompt_toolkit dependency via pip:

> pip install prompt-toolkit

Download the latest from github and unzip it to xonsh-master.

Now install xonsh:

> cd xonsh-master
> python install

Next, run xonsh:

> xonsh
snail@home ~ $

Tips and Tricks

Nice colors

The dark red and blue colors are completely unreadable in Windows’ default terminal.


There are ways to configure the colors of the old terminal, 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.

$INTENSIFY_COLORS_ON_WIN has the following effect:b

On Windows 10:

Windows 10 supports true color in the terminal, so on Windows 10 Xonsh will use a style with hard coded colors instead of the terminal colors.

On older Windows:

Xonsh replaces some of the unreadable dark colors with more readable alternatives (e.g. blue becomes cyan).

The new Windows terminal

The best option on windows is to use the new Windows Terminal developed by Microsoft as an open source project. The new terminal supports has many nice features including Unicode rendering.

It is highly recommended and can easily be installed from the Windows Store:

Unicode support in Windows terminal

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 console “conhost” on Windows.

Luckily, Microsoft is developing a new Windows terminal as an open source project. The new terminal supports all the nice features of that you find in linux terminals. It is highly recommended and can easily be installed from the Windows Store:

Unicode support in Windows terminal