OSX Guide


You can install xonsh using a package manager including homebrew, macports, conda, pip, or from source.


$ brew install xonsh


$ sudo port 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 macOS


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

$ pip3 install gnureadline

Path Helper

macOS provides a path helper, which by default configures paths in bash and other POSIX or C shells. Without including these paths, common tools including those installed by Homebrew may be unavailable. See /etc/profile for details on how it is done. To ensure the path helper is invoked on xonsh (for all users), add the following to /etc/xonshrc:

source-bash $(/usr/libexec/path_helper -s)

To incorporate the whole functionality of /etc/profile:

source-bash --seterrprevcmd "" /etc/profile

Tab completion

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.

Bash completion comes from <https://github.com/scop/bash-completion> which suggests you use a package manager to install it, this manager will also install a new version of bash without affecting /bin/bash. Xonsh also needs to be told where the bash shell file that builds the completions is, this has to be added to $BASH_COMPLETIONS. The package includes completions for many Unix commands.

Common packaging systems for MacOs include

  • Homebrew where the bash-completion2 package needs to be installed.

    $ brew install bash-completion2

    This will install the bash_completion file in /usr/local/share/bash-completion/bash_completion which is in the current xonsh code and so should just work.

  • MacPorts where the bash-completion port needs to be installed.

    $ sudo port install bash-completion

    This includes a bash_completion file that needs to be added to the environment.

    $ $BASH_COMPLETIONS.insert(0, '/opt/local/share/bash-completion/bash_completion')

Note that the bash completion project page gives the script to be called as in …/profile.d/bash_completion.sh which will the call the script mentioned above and one in $XDG_CONFIG_HOME . Currently xonsh seems only to be able to read the first script directly.


Xonsh currently has the following external dependencies,

Run Time:

  1. Python v3.5+

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 >= 2.0: advanced readline library, line-editing

  2. pygments: pygments >=2.2: 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

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!