Install & Compatibility
Where this runs
tested against v0.19.9 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.920 runs
installs and imports cleanly · install 0.0s · import 0.000s · 29.1MB
glibcpy 3.10–3.920 runs
installs and imports cleanly · install 3.5s · import 0.000s · 26MB
28MB installed
● package 28MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
@
✓ This is a special global object automatically available in the xonsh shell session. It doesn't require an explicit import statement.
✗ from xonsh import @
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
✓ from xonsh.lib import lazyjson
✗ from xonsh import lazyjson
The 'xonsh.lazyjson' module has been deprecated; users should now import 'lazyjson' from 'xonsh.lib.lazyjson'.
xonsh.lib.lazyasd
✓ from xonsh.lib import lazyasd
✗ from xonsh import lazyasd
Similar to lazyjson, 'xonsh.lazyasd' has been deprecated. The correct import path is now 'xonsh.lib.lazyasd'.
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)}")
xonsh --version
Debug
Known issues
breakingAliases `ipynb` and `scp-resume` were removed from built-in aliases, and `xonsh-reset` was renamed to `xreset`.fixUpdate scripts and configurations to use `xreset` instead of `xonsh-reset`, and find alternatives for `ipynb` and `scp-resume` if previously used.
affects: 0.22.0 and later
gotchaInstalling 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.fixUse 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.
affects: All versions
gotchaXonsh 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.fixRun 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.
affects: All versions
gotchaQuotes 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.fixIf 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"`.
affects: All versions
Upgrade
Version history
0.23.8latest on PyPI · released May 30, 2026
Audit
Dependencies
pythonrequiredCore dependency as xonsh is a Python-powered shell.
prompt_toolkitoptionalProvides advanced interactive shell features like syntax highlighting and autosuggestions.
pygmentsoptionalUsed for syntax highlighting and colorization.
ujsonoptionalPotentially for faster JSON processing, though not explicitly stated as critical.
pyperclipoptionalFor clipboard functionality.