XONSH(1)

🦋 NAME 🦋

xonsh — Pythonish, BASHwards looking shell 💅

---

💖 DESCRIPTION 💖

okay so. xonsh is a Python-ish shell language AND a command prompt, bestie. unlike other shells, xonsh is based on Python, with extra syntax sprinkled on top that makes calling subprocess commands, messing with the environment, and wrangling the file system actually easy. and the range? it supports all normal Python constructs plus a subset of the ones you'd find in bash. it's giving "why not both" and honestly it ate. 🔥

here's the usage, verbatim, no cap:

usage: xonsh [-h] [-V] [-c COMMAND] [-n] [-i] [-l] [--rc RC [RC ...]]

       [--no-rc] [--no-env] [--no-script-cache] [--cache-everything] [-D
       ITEM] [-st SHELL_TYPE] [--timings] [--save-origin-env]
       [--load-origin-env] [script-file] ...

xonsh

✨ positional arguments ✨

• script-file — if this is here, xonsh runs the script in script-file and then dips out. bye! 👋
• args — extra arguments you wanna hand off to the script that script-file points at.

🌸 options 🌸

• -h, --help — shows the help and exits. classic.
• -V, --version — shows version info and exits. also classic.
• -c COMMAND — runs a single command, then exits. one and done, main character behavior.
• -n, --no-execute — parses and compiles the code but does not execute it. exits non-zero if there are errors. and bestie, if you want more options — like checking several files at once — go use the xonsh check subcommand instead.
• -i, --interactive — forces interactive mode. you're gonna interact whether you like it or not 💅
• -l, --login — runs as a login shell.
• --rc RC [RC ...] — the xonshrc files to load. these can be xonsh files or directories that contain xonsh files. flexible queen 🎀
• --no-rc — don't load any xonsh RC files. heads up: the --rc argument gets ignored if --no-rc is set.
• --no-env — don't inherit your parent environment variables.
• --no-script-cache — doesn't cache scripts when they run. no hoarding here.
• --cache-everything — uses a cache, even for interactive commands. maximalist energy 😌
• -D ITEM — defines an environment variable, written as -DVAR=VAL, or inherits an existing variable with -DVAR. you can use this one many times.
• -st, --shell-type SHELL_TYPE — what kind of shell should be used. possible options: b, best, d, dumb, ptk, prompt-toolkit, prompt_toolkit, rand, random, rl, readline.

⚠️ Warning! If you set this, it overrides the $SHELL_TYPE variable. it's not a suggestion, it's a takeover 🔥

• --timings — prints timing info before the prompt shows up. super useful when you're hunting down performance issues and investigating startup times. we love a diagnostics moment.
• --save-origin-env — saves the origin environment variables before running xonsh. then use --load-origin-env to run xonsh with that saved origin environment. it's a matching set, iykyk 🫶
• --load-origin-env — loads the origin environment variables that were saved before running xonsh by using --save-origin-env.

👑 subcommands 👑

• format — formats xonsh source files. run xonsh format --help for the options.
• check — checks xonsh source files for syntax errors without running them. run xonsh check --help for the options.
• lint — lints xonsh source files for likely mistakes. run xonsh lint --help for the options.

---

🎀 FILES 🎀

so the run control file is written in xonsh script and gets executed once at start-up. one shot, one opportunity.

• /etc/xonshrc — system-wide run control file 🌈
• ~/.xonshrc — per-user run control file ✨

and plot twist: on top of the run control file, there's a JSON formatted static file you can use to set runtime parameters and environment variables before the xonshrc files get executed. so it runs first. it's the opening act. 💜

• $XDG_CONFIG_HOME/xonsh/config.json — per-user static config file ⭐

---

and that's the whole page bestie — this was xonsh, version xonsh/0.24.0, from August 2026, served fresh out of the User Commands manual. periodt. 💅💖