OSX Guide


You can install xonsh using homebrew, conda, pip, or from source.


$ brew install xonsh


$ conda config --add channels conda-forge
$ conda install xonsh


$ pip3 install xonsh

source: Download the source from github (zip file), then run the following from the source directory,

$ python3 setup.py install

Extras for OSX

On Mac OSX, it is strongly recommended to install the gnureadline library if using the readline shell. gnureadline can be installed via pip:

$ pip3 install gnureadline

Xonsh has support for using bash completion files on the shell, to use it you need to install the bash-completion package. The regular bash-completion package uses v1 which mostly works, but occasionally has rough edges so we recommend using bash-completion v2 which is installed using the bash-completion2 package.

$ brew install bash-completion2


Xonsh currently has the following external dependencies,

Run Time:

  1. Python v3.4+
  2. PLY (optional, included with xonsh)

Pip supports “extra” dependencies in the form of xonsh[ptk,linux], where the list in the brackets identify the optional features

Xonsh currently has the following extras

  1. ptk: prompt-toolkit: advanced readline library, line-editing
  2. pygments: syntax-highlighting
  3. proctitle: setproctitle: change the title of terminal to reflect the current subprocess
  4. linux: distro: linux specific platform information
  5. mac: gnureadline: GNU’s featureful version of readline
  6. win: win_unicode_console: enables the use of Unicode in windows consoles

In addition, xonsh integrates with Jupyter, an in-browser REPL, enabling the use of xonsh in jupyter notebooks

Development Dependencies

If you want to develop xonsh, it is extremely recommended to install the dependencies listed in requirements-docs.txt (to generate documentation) and requirements-tests.txt (to run the test suite).


See the xonsh customization guide for more details on setting up xonsh!