https://github.com/anki-code/xonsh-install
Best way to install xonsh on Linux or macOS and using it as core shell.
https://github.com/anki-code/xonsh-install
conda mamba micromamba miniconda xonsh xonsh-dev xontrib
Last synced: about 1 month ago
JSON representation
Best way to install xonsh on Linux or macOS and using it as core shell.
- Host: GitHub
- URL: https://github.com/anki-code/xonsh-install
- Owner: anki-code
- License: bsd-2-clause
- Created: 2024-04-07T20:22:42.000Z (about 1 year ago)
- Default Branch: main
- Last Pushed: 2025-03-04T13:26:15.000Z (about 2 months ago)
- Last Synced: 2025-03-17T22:55:14.796Z (about 1 month ago)
- Topics: conda, mamba, micromamba, miniconda, xonsh, xonsh-dev, xontrib
- Language: Shell
- Homepage:
- Size: 163 KB
- Stars: 18
- Watchers: 2
- Forks: 0
- Open Issues: 3
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
Best way to install xonsh on macOS or Linux and using it as core shell.
If you like the idea click ⭐ on the repo and tweet.
## Motivation
Xonsh is a Python-based shell, and to run xonsh you must have Python installed. The Python version and its packages can be installed and located anywhere and when you execute `import` or any other Python code during a xonsh session, it will be executed in the Python environment that was used to run the current instance of xonsh. You must have good knowledge of this process after reading [xonsh-cheatsheet](https://github.com/anki-code/xonsh-cheatsheet/).
When xonsh becomes a core shell it's needed to keep python environment with xonsh stable, predictable and independent of any changes in the system. The lightweight environment managers like `venv`, `pipx` or `rye` will not help with this and it's needed to use package managers that have ability to install isolated python invironment as core feature e.g. `miniconda`, `micromamba`.
## mamba-install-xonsh
The `mamba-install-xonsh.sh` script creates independent python environment for xonsh using [mamba](https://mamba.readthedocs.io/) in `$TARGET_DIR` without affect any other things on the system. It's isolated xonsh-specific environment that can't be affected by upgrading the system packages, python version and other experiments around environments. You can use `xpip` and `xmamba` to install packages into this environment intentionally.
**Install stable**: the latest xonsh release with mostly tested python version:
```xsh
TARGET_DIR=$HOME/.local/xonsh-env PYTHON_VER=3.11 XONSH_VER='xonsh[full]>=0.19.0' \
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/anki-code/xonsh-install/main/mamba-install-xonsh.sh)"
```
**Install the front line**: xonsh from main git branch with stable python version (known issues: [#5166](https://github.com/xonsh/xonsh/issues/5166)):
```xsh
TARGET_DIR=$HOME/.local/xonsh-env PYTHON_VER=3.12 XONSH_VER='git+https://github.com/xonsh/xonsh#egg=xonsh[full]' \
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/anki-code/xonsh-install/main/mamba-install-xonsh.sh)"
```
**Install with stuff**: preinstall and preload [xontribs](https://github.com/topics/xontrib) (good for ssh and as manual alternative to [xxh](https://github.com/xxh/xxh)):
```xsh
TARGET_DIR=$HOME/.local/xonsh-env PYTHON_VER=3.11 XONSH_VER='git+https://github.com/xonsh/xonsh#egg=xonsh[full]' \
PIP_INSTALL="uv xontrib-sh xontrib-jump-to-dir xontrib-dalias xontrib-pipeliner xontrib-whole-word-jumping" \
XONSHRC="\$XONSH_HISTORY_BACKEND = 'sqlite'; xontrib load -s sh jump_to_dir pipeliner whole_word_jumping dalias; \$PROMPT = \$PROMPT.replace('{prompt_end}', '\n{prompt_end}')" \
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/anki-code/xonsh-install/main/mamba-install-xonsh.sh)"
```
### Usage
Now forget about the cases where manipulations around python and packages break the shell unintended. Use `pip`, `brew` and other package managers without corrupting xonsh-env.
After installation:
* `xonsh` refers to `~/.local/xonsh-env/xbin/xonsh`.
* `xpip` refers to `~/.local/xonsh-env/bin/python -m pip`.
* You can run `source xmamba` to activate mamba. See below.
Additions:
* `xbin-xonsh` is to run xonsh from xonsh-env if xonsh overwritten by `$PATH`.
* `xbin-python` is to run python from xonsh-env.
* Use executable script from xonsh-env:
* `xbin-hidden` is to list xonsh-env internal hidden `bin` directory. E.g. `xpip install lolcat && xbin-hidden # lolcat`.
* `xbin-add` is to add executer from hidden `bin` to visible `xbin`. E.g. `xbin-add lolcat`.
* `xbin-list` is to list visible `xbin` directory. E.g. `xbin-list # lolcat`.
* `xbin-del` is to delete executer from `xbin`. E.g. `xbin-del lolcat`. It will stay in `bin`.
### Tips and tricks
#### Using mamba from xonsh-env
To bind xonsh-env micromamba to `xmamba` alias run:
```xsh
source xmamba
```
Now you can:
```xsh
xmamba activate base # Env where xonsh was installed.
pip install lolcat # Install `lolcat` into `base` env.
xmamba deactivate
xmamba create --name myenv python=3.12
xmamba activate myenv
pip install lolcat # Install `lolcat` into `myenv`.
xmamba deactivate
```
#### Cleaning
If you have no plans to use `xmamba` [clean](https://fig.io/manual/mamba/clean) the disk space:
```xsh
source xmamba
xmamba clean -a
```
### Uninstall
Just delete `$TARGET_DIR` e.g. `rm -rf ~/.local/xonsh-env/` by default.
### Known issues
#### Do not blindly use as a login shell
We do not recommend to use xonsh as a [login shell](https://linuxhandbook.com/login-shell/) if you are not feel you strong and experienced. Most tools are waiting that login shell is POSIX-compliant you can face with issues when some tool is trying to run POSIX-compatible commands in xonsh.
#### `std::bad_alloc`
If you see `terminate called after throwing an instance of 'std::bad_alloc'` just delete the target directory (e.g. `rm -rf ~/.local/xonsh-env/`) and try to install again.
## Another way to install xonsh
If you know how to install xonsh using another package manager - PR is welcome!
## See also
* [xonsh-cheatsheet](https://github.com/anki-code/xonsh-cheatsheet/tree/main) - Cheat sheet for xonsh shell with copy-pastable examples. The best doc for the new users.
* [xonsh.AppImage](https://xon.sh/appimage.html) - one executable file which contains both xonsh and Python. AppImage allows xonsh to be run on any AppImage supported Linux distribution without installation or root access.