{"id":7872,"library":"xonsh","title":"xonsh: Python-powered Shell","description":"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).","status":"active","version":"0.22.8","language":"en","source_language":"en","source_url":"https://github.com/xonsh/xonsh","tags":["shell","python","command-line","cli","cross-platform","productivity"],"install":[{"cmd":"pip install 'xonsh[full]' --user","lang":"bash","label":"Recommended pip install (for user)"},{"cmd":"conda install xonsh -c conda-forge","lang":"bash","label":"Conda install"},{"cmd":"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)\"","lang":"bash","label":"Mamba installer (recommended for isolated environment)"}],"dependencies":[{"reason":"Core dependency as xonsh is a Python-powered shell.","package":"python","optional":false},{"reason":"Provides advanced interactive shell features like syntax highlighting and autosuggestions.","package":"prompt_toolkit","optional":true},{"reason":"Used for syntax highlighting and colorization.","package":"pygments","optional":true},{"reason":"Potentially for faster JSON processing, though not explicitly stated as critical.","package":"ujson","optional":true},{"reason":"For clipboard functionality.","package":"pyperclip","optional":true}],"imports":[{"note":"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.","wrong":"from xonsh import @","symbol":"@","correct":"This is a special global object automatically available in the xonsh shell session. It doesn't require an explicit import statement."},{"note":"The 'xonsh.lazyjson' module has been deprecated; users should now import 'lazyjson' from 'xonsh.lib.lazyjson'.","wrong":"from xonsh import lazyjson","symbol":"xonsh.lib.lazyjson","correct":"from xonsh.lib import lazyjson"},{"note":"Similar to lazyjson, 'xonsh.lazyasd' has been deprecated. The correct import path is now 'xonsh.lib.lazyasd'.","wrong":"from xonsh import lazyasd","symbol":"xonsh.lib.lazyasd","correct":"from xonsh.lib import lazyasd"}],"quickstart":{"code":"import os\n\n# To run xonsh, simply execute 'xonsh' in your terminal after installation.\n# This example demonstrates mixing Python and shell commands within a .xonshrc file or interactively.\n\n# Python mode: Assign a variable\nname = 'xonsh_user'\n\n# Subprocess mode: Echo the variable using Python substitution\nprint(f\"echo Hello, @(name)!\")\n\n# Mixing Python and shell for a loop\nfor i in range(3):\n    print(f\"echo Loop iteration: @(i)\")\n\n# Accessing environment variables (Python style)\npath_var = os.environ.get('PATH', '')\nprint(f\"Current PATH has {len(path_var.split(os.pathsep))} entries.\")\n\n# Running a shell command and capturing its output (subprocess style)\noutput = $(ls -l)\nprint(f\"'ls -l' command output length: {len(output)}\")","lang":"python","description":"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."},"warnings":[{"fix":"Update scripts and configurations to use `xreset` instead of `xonsh-reset`, and find alternatives for `ipynb` and `scp-resume` if previously used.","message":"Aliases `ipynb` and `scp-resume` were removed from built-in aliases, and `xonsh-reset` was renamed to `xreset`.","severity":"breaking","affected_versions":"0.22.0 and later"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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\"`.","message":"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.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"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.","cause":"The Python package was installed in a different virtual environment than the one xonsh is currently running in.","error":"ModuleNotFoundError: No module named 'some_package'"},{"fix":"Add `unset module` and `unset scl` to your `~/.bashrc` file to prevent Bash from attempting to import these functions when xonsh launches.","cause":"Conflicts with Bash configurations, particularly on Linux systems, when xonsh tries to load certain shell modules or functions defined in `.bashrc`.","error":"bash: module: line 1: syntax error: unexpected end of file"},{"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.","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.","error":"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."}]}