xonsh: Python-powered Shell

0.22.8 · active · verified Thu Apr 16

xonsh (pronounced 'consh') is a modern, full-featured, and cross-platform shell language and command prompt powered by Python. It seamlessly integrates Python 3 with shell functionality, allowing users to mix Python code and shell commands. The current version is 0.22.8, and it maintains a regular release cadence, supporting the latest minor Python versions (currently Python >=3.11).

Common errors

```
ModuleNotFoundError: No module named 'some_package'
```
cause The Python package was installed in a different virtual environment than the one xonsh is currently running in.

fix Ensure xonsh is running in the correct environment where the package is installed. Use `xpip install some_package` to install packages directly into the xonsh environment, or launch xonsh from within the activated virtual environment that contains the desired packages. Use `xcontext` to inspect the current xonsh environment.
```
bash: module: line 1: syntax error: unexpected end of file
```
cause Conflicts with Bash configurations, particularly on Linux systems, when xonsh tries to load certain shell modules or functions defined in `.bashrc`.

fix Add `unset module` and `unset scl` to your `~/.bashrc` file to prevent Bash from attempting to import these functions when xonsh launches.
```
xonsh --version returns an old version, or 'xonsh' already seems to be installed, Not modifying existing installation in ~/.local/share/pipx/venvs/xonsh'. Pass '–force' to force installation.
```
cause An older version of xonsh is detected by a package manager or an IDE extension, preventing the installation or update of a newer version.

fix Manually uninstall the old xonsh version using `pipx uninstall xonsh` or `pip uninstall xonsh` within your WSL or relevant environment. Then, proceed with the desired installation method (e.g., `pip install 'xonsh[full]'`) or allow your IDE/tool to reinstall it.

Warnings

breaking Aliases `ipynb` and `scp-resume` were removed from built-in aliases, and `xonsh-reset` was renamed to `xreset`.
Fix: Update scripts and configurations to use `xreset` instead of `xonsh-reset`, and find alternatives for `ipynb` and `scp-resume` if previously used.
gotcha Installing xonsh via system package managers (e.g., `apt`, `pacman`, `brew`) is not recommended, especially as a login shell. This can lead to outdated versions, missing dependencies, and potential breakage with system Python updates.
Fix: Use isolated environment managers like `pipx`, `mamba`, or `conda` for installation, or install directly into a Python virtual environment. This ensures a stable and predictable xonsh environment.
gotcha Xonsh is a non-POSIX compatible shell. Attempting to use it as a login shell via `chsh` or expecting it to execute Bash scripts directly or perfectly translate all Bash idioms can lead to unexpected behavior or breakage.
Fix: Run xonsh from within your existing terminal emulator (e.g., `bash` or `zsh`) or configure your terminal emulator to launch xonsh as its default shell, rather than changing your system's login shell. Consult the 'Bash to Xonsh Translation Guide' for equivalents of common Bash patterns.
gotcha Quotes in the middle of a shell command argument are handled as literal parts of the argument in xonsh, unlike traditional shells where they might be removed. This can lead to unexpected parsing by external commands.
Fix: If an external command misinterprets an argument with embedded quotes, wrap the entire argument in a string to ensure it's passed as a single, literal value. For example, use `some_command "--arg=value with spaces"` instead of `some_command --arg="value with spaces"`.

Install

pip install 'xonsh[full]' --user Recommended pip install (for user)
conda install xonsh -c conda-forge Conda install
TARGET_DIR=$HOME/.local/xonsh-env PYTHON_VER=3.11 XONSH_VER='xonsh[full]' \ /bin/bash -c "$(curl -fsSL https://xon.sh/install/mamba-install-xonsh.sh)" Mamba installer (recommended for isolated environment)

Imports

@
wrong:
```
from xonsh import @
```
correct:
```
This is a special global object automatically available in the xonsh shell session. It doesn't require an explicit import statement.
```
The '@' object represents the current xonsh session and provides access to environment variables (@.env), last command (@.lastcmd), and other session-specific functionalities. It is a builtin and not imported like a regular Python module.
xonsh.lib.lazyjson
wrong:
```
from xonsh import lazyjson
```
correct:
```
from xonsh.lib import lazyjson
```
The 'xonsh.lazyjson' module has been deprecated; users should now import 'lazyjson' from 'xonsh.lib.lazyjson'.
xonsh.lib.lazyasd
wrong:
```
from xonsh import lazyasd
```
correct:
```
from xonsh.lib import lazyasd
```
Similar to lazyjson, 'xonsh.lazyasd' has been deprecated. The correct import path is now 'xonsh.lib.lazyasd'.

Quickstart

After installing, simply type `xonsh` in your terminal to start the shell. The quickstart demonstrates how to declare Python variables, use them in shell commands via Python substitution (`@(variable)`), execute loops that mix both modes, and interact with environment variables and subprocess outputs. This code snippet shows Python syntax that would typically be placed in a `.xonshrc` file or run directly in the xonsh prompt, illustrating the core hybrid nature of the shell.

import os

# To run xonsh, simply execute 'xonsh' in your terminal after installation.
# This example demonstrates mixing Python and shell commands within a .xonshrc file or interactively.

# Python mode: Assign a variable
name = 'xonsh_user'

# Subprocess mode: Echo the variable using Python substitution
print(f"echo Hello, @(name)!")

# Mixing Python and shell for a loop
for i in range(3):
    print(f"echo Loop iteration: @(i)")

# Accessing environment variables (Python style)
path_var = os.environ.get('PATH', '')
print(f"Current PATH has {len(path_var.split(os.pathsep))} entries.")

# Running a shell command and capturing its output (subprocess style)
output = $(ls -l)
print(f"'ls -l' command output length: {len(output)}")

view raw JSON →