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
Be sure to install the version with Python3.4 or later. Xonsh is not yet supported on legacy Python (2.7).
Install xonsh with the following command:
> conda config --add channels conda-forge
> conda install xonsh
Note
For the bleeding edge development version use conda install -c xonsh/channel/dev 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
While prompt-toolkit is considered an optional dependency, it is the recommended alternative to pyreadline for Windows users. For Windows, it is recommended to use a replacement console emulator. Good choices are cmder or conemu.
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¶
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 using pip or conda.
> pip install win_unicode_console
> conda install --channel xonsh win_unicode_console
Running Under Cygwin¶
Cygwin support in xonsh is a work in progress. Currently, there are some
issues. Most noticeably, running xonsh by running the xonsh
command from
within Cygwin bash will cause xonsh to background itself after every command
that is run. This should be addressed in a future version, but in the
meantime, invoking xonsh via exec xonsh
should work.
It is possible to use xonsh as your default shell in Cygwin by adding exec
xonsh
to your .bash_profile
file.