OSX Guide¶
Installation¶
You can install xonsh using a package manager including homebrew, macports, conda, pip, or from source.
homebrew:
$ brew install xonsh
MacPorts:
$ sudo port install xonsh
conda:
$ conda config --add channels conda-forge
$ conda install xonsh
pip:
$ 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¶
readline¶
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.
Dependencies¶
Xonsh currently has the following external dependencies,
Run Time:
- Python v3.4+
- 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
ptk
: prompt-toolkit: advanced readline library, line-editingpygments>=2.2
: syntax-highlightingproctitle
: setproctitle: change the title of terminal to reflect the current subprocesslinux
: distro: linux specific platform informationmac
: gnureadline: GNU’s featureful version of readlinewin
: 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).
Customization¶
See the xonsh customization guide for more details on setting up xonsh
!