Skip to content
Back to top
View this page
Edit this page

# Environment Variables

The following displays information about the environment variables that affect xonsh in some way. It also lists their default values, if applicable.

System Environment Variables
$HOSTNAME | $HOSTTYPE
$OLDPWD | $PATH
$PATHEXT | $PWD
$SHLVL | $TERM
$XDG_CACHE_HOME | $XDG_CONFIG_HOME
$XDG_DATA_DIRS | $XDG_DATA_HOME

General
$UPDATE_OS_ENVIRON | $XONSHRC
$XONSHRC_DIR | $XONSH_COLOR_STYLE
$XONSH_CONFIG_DIR | $XONSH_DATA_DIR
$XONSH_DEBUG | $XONSH_DEBUG_BREAKPOINT_ENGINE
$XONSH_ENCODING | $XONSH_ENCODING_ERRORS
$XONSH_ENV_PATTERN_DIRS | $XONSH_ENV_PATTERN_PATH
$XONSH_INTERACTIVE | $XONSH_LOGIN
$XONSH_MODE | $XONSH_ORIGIN_ENV_FILE
$XONSH_SOURCE | $XONSH_STORE_STDIN
$XONSH_STYLE_OVERRIDES | $XONSH_SYS_CONFIG_DIR

Subprocess Settings
$LAST_RETURN_CODE | $THREAD_SUBPROCS
$XONSH_APPEND_NEWLINE | $XONSH_BUILTINS_TO_CMD
$XONSH_CAPTURE_ALWAYS | $XONSH_PROC_FREQUENCY
$XONSH_SUBPROC_CAPTURED_PRINT_STDERR | $XONSH_SUBPROC_CMD_RAISE_ERROR
$XONSH_SUBPROC_OUTPUT_FORMAT | $XONSH_SUBPROC_RAISE_ERROR
$XONSH_SUBPROC_TRACE |

Error Handling Settings
$XONSH_SHOW_TRACEBACK | $XONSH_TRACEBACK_LOGFILE

Jobs Settings
$AUTO_CONTINUE |

Language and locale settings.
$LANG | $LC_COLLATE
$LC_CTYPE | $LC_MESSAGES
$LC_MONETARY | $LC_NUMERIC
$LC_TIME | $XONSH_DATETIME_FORMAT

Cache Settings
$COMMANDS_CACHE_SAVE_INTERMEDIATE | $ENABLE_COMMANDS_CACHE
$XONSH_CACHE_DIR | $XONSH_CACHE_EVERYTHING
$XONSH_CACHE_SCRIPTS | $XONSH_COMMANDS_CACHE_READ_DIR_ONCE
$XONSH_COMMANDS_CACHE_TRACE |

cd Behavior
$AUTO_CD | $AUTO_PUSHD
$CDPATH | $COMPLETE_DOTS
$DIRSTACK_SIZE | $PUSHD_MINUS
$PUSHD_SILENT |

Interpreter Behavior
$DOTGLOB | $EXPAND_ENV_VARS
$FOREIGN_ALIASES_OVERRIDE | $FOREIGN_ALIASES_SUPPRESS_SKIP_MESSAGE
$GLOB_SORTED | $XONSH_SUBPROC_ARG_EXPANDUSER

Xontrib Settings
$XONTRIBS_AUTOLOAD_DISABLED |

Interactive Prompt
$BOTTOM_TOOLBAR | $COLOR_INPUT
$COLOR_RESULTS | $DYNAMIC_CWD_ELISION_CHAR
$DYNAMIC_CWD_WIDTH | $IGNOREEOF
$INDENT | $LS_COLORS
$MULTILINE_PROMPT | $MULTILINE_PROMPT_POS
$MULTILINE_PROMPT_PRE | $PRETTY_PRINT_RESULTS
$PROMPT | $PROMPT_FIELDS
$PROMPT_REFRESH_INTERVAL | $PROMPT_TOKENS_FORMATTER
$RIGHT_PROMPT | $SHELL_TYPE
$SUGGEST_COMMANDS | $SUGGEST_MAX_NUM
$SUGGEST_THRESHOLD | $SUPPRESS_BRANCH_TIMEOUT_MESSAGE
$TITLE | $UPDATE_PROMPT_ON_KEYPRESS
$VC_BRANCH_TIMEOUT | $VC_GIT_INCLUDE_UNTRACKED
$VC_HG_SHOW_BRANCH | $VIRTUAL_ENV
$XONSH_HISTORY_MATCH_ANYWHERE | $XONSH_PROMPT_SHOW_SUBPROC_ERROR
$XONSH_STDERR_POSTFIX | $XONSH_STDERR_PREFIX
$XONSH_SUPPRESS_WELCOME |

Prompt Toolkit shell
$AUTO_SUGGEST_IN_COMPLETIONS | $MOUSE_SUPPORT
$PROMPT_TOOLKIT_COLOR_DEPTH | $PTK_STYLE_OVERRIDES
$VI_MODE | $XONSH_AUTOPAIR
$XONSH_COPY_ON_DELETE | $XONSH_CTRL_BKSP_DELETION
$XONSH_PROMPT_AUTO_SUGGEST | $XONSH_PROMPT_CURSOR_SHAPE
$XONSH_PROMPT_NEXT_CMD | $XONSH_PROMPT_NEXT_CMD_SUGGESTION
$XONSH_USE_SYSTEM_CLIPBOARD |

Asynchronous Prompt
$ASYNC_INVALIDATE_INTERVAL | $ASYNC_PROMPT_THREAD_WORKERS
$ENABLE_ASYNC_PROMPT |

Interactive Prompt History
$HISTCONTROL | $XONSH_HISTORY_BACKEND
$XONSH_HISTORY_FILE | $XONSH_HISTORY_IGNORE_REGEX
$XONSH_HISTORY_SAVE_CWD | $XONSH_HISTORY_SIGINT_FLUSH
$XONSH_HISTORY_SIZE | $XONSH_STORE_STDOUT

Tab-completion behavior.
$ALIAS_COMPLETIONS_OPTIONS_BY_DEFAULT | $ALIAS_COMPLETIONS_OPTIONS_LONGEST
$BASH_COMPLETIONS | $CMD_COMPLETIONS_SHOW_DESC
$COMPLETIONS_BRACKETS | $COMPLETION_QUERY_LIMIT
$FUZZY_PATH_COMPLETION | $SUBSEQUENCE_PATH_COMPLETION
$XONSH_BASH_PATH_OVERRIDE | $XONSH_COMPLETER_DIRS
$XONSH_COMPLETER_EMOJI_PREFIX | $XONSH_COMPLETER_MODE
$XONSH_COMPLETER_SYMBOLS_PREFIX | $XONSH_COMPLETER_TRACE

Prompt Toolkit tab-completion
$COMPLETIONS_CONFIRM | $COMPLETIONS_DISPLAY
$COMPLETIONS_MENU_ROWS | $COMPLETION_IN_THREAD
$COMPLETION_MODE | $UPDATE_COMPLETIONS_ON_KEYPRESS

Windows OS
$ANSICON | $FORCE_POSIX_PATHS
$INTENSIFY_COLORS_ON_WIN | $XONSH_WIN_CONSOLE_HISTORY_BUFFERS

Deprecated settings.
$AUTO_SUGGEST | $RAISE_SUBPROC_ERROR

## System Environment Variables

Common, well-known variables inherited from the surrounding OS / shell (POSIX-standard and XDG Base Directory Specification). They are not xonsh-specific — xonsh only provides sensible defaults and lets scripts read/write them the same way any other shell would.

### $HOSTNAME

Automatically set to the name of the current host.

configurable: True

default: <function SystemSetting.<lambda> at 0x7cc35c350250>

store_as_str: False

### $HOSTTYPE

Automatically set to a string that fully describes the system type on which xonsh is executing.

configurable: True

default: <function SystemSetting.<lambda> at 0x7cc35c350300>

store_as_str: False

### $OLDPWD

Used to represent a previous present working directory.

configurable: False

default: ‘.’

store_as_str: False

### $PATH

List of strings representing where to look for executables.

configurable: True

default:

- Windows: `Path` value from registry `HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\Session Manager\Environment`

- macOS: `('/usr/local/bin', '/usr/bin', '/bin', '/usr/sbin', '/sbin')`

- Linux/Cygwin/MSYS (arch-like): `('/usr/local/sbin', '/usr/local/bin', '/usr/bin', '/usr/bin/site_perl', '/usr/bin/vendor_perl', '/usr/bin/core_perl')`

- Linux/Cygwin/MSYS (other): `('~/bin', '/usr/local/sbin', '/usr/local/bin', '/usr/sbin', '/usr/bin', '/sbin', '/bin', '/usr/games', '/usr/local/games')`

store_as_str: False

### $PATHEXT

Sequence of extension strings (e.g., `.EXE`) for filtering valid executables by. Each element must be uppercase.

configurable: True

default: []

store_as_str: False

### $PWD

Current working directory.

configurable: False

default: os.getcwd()

store_as_str: False

### $SHLVL

Shell nesting level typed as integer, mirrors bash’s `$SHLVL`.

configurable: False

default: 0

store_as_str: False

### $TERM

TERM is sometimes set by the terminal emulator. This is used (when valid) to determine whether the terminal emulator can support the selected shell, or whether or not to set the title. Users shouldn’t need to set this themselves. Note that this variable should be set as early as possible in order to ensure it is effective. Here are a few options:

- Set this from the program that launches xonsh. On POSIX systems, this can be performed by using env, e.g. `/usr/bin/env TERM=xterm-color xonsh` or similar.

- From the xonsh command line, namely `xonsh -DTERM=xterm-color`.

- In the config file with `{"env": {"TERM": "xterm-color"}}`.

- Lastly, in xonshrc with `$TERM`

Ideally, your terminal emulator will set this correctly but that does not always happen.

configurable: False

default: not defined

store_as_str: False

### $XDG_CACHE_HOME

The base directory relative to which user-specific non-essential data files should be stored.

configurable: True

default: `~/.cache`

store_as_str: False

### $XDG_CONFIG_HOME

Open desktop standard configuration home dir. This is the same default as used in the standard.

configurable: False

default: `~/.config`

store_as_str: False

### $XDG_DATA_DIRS

A list of directories where system level data files are stored.

configurable: True

default: On Windows: `[%ProgramData%]` (normally C:ProgramData)

  - More Info: https://docs.microsoft.com/en-us/windows-hardware/customize/desktop/unattend/microsoft-windows-shell-setup-folderlocations-programdata

On Linux and Unix based systemd it is the same as in open-desktop standard: `['/usr/share', '/usr/local/share']`

store_as_str: False

### $XDG_DATA_HOME

Open desktop standard data home dir. This is the same default as used in the standard.

configurable: True

default: `~/.local/share`

store_as_str: False

## General

### $UPDATE_OS_ENVIRON

If True `os_environ` will always be updated when the xonsh environment changes. The environment can be reset to the default value by calling `__xonsh__.env.undo_replace_env()`

configurable: True

default: False

store_as_str: False

### $XONSHRC

A list of the locations of run control files, if they exist. User defined run control file will supersede values set in system-wide control file if there is a naming collision. `$THREAD_SUBPROCS=None` when reading in run control files.

configurable: True

default: `['$XONSH_SYS_CONFIG_DIR/xonshrc', '$XONSH_CONFIG_DIR/xonsh/rc.xsh', '~/.xonshrc']`

store_as_str: False

### $XONSHRC_DIR

A list of directories, from which all .xsh|.py files will be loaded at startup, sorted in lexicographic order. Files in these directories are loaded after any files in XONSHRC.

configurable: True

default: `['$XONSH_SYS_CONFIG_DIR/rc.d', '$XONSH_CONFIG_DIR/rc.d']`

store_as_str: False

### $XONSH_COLOR_STYLE

Sets the color style for xonsh colors. This is a style name, not a color map. Run `xonfig styles` to see the available styles.

configurable: True

default: ‘default’

store_as_str: False

### $XONSH_CONFIG_DIR

This is the location where xonsh user-level configuration information is stored.

configurable: True

default: `$XDG_CONFIG_HOME/xonsh`

store_as_str: False

### $XONSH_DATA_DIR

This is the location where xonsh data files are stored, such as history, generated completers …

configurable: True

default: `$XDG_DATA_HOME/xonsh`

store_as_str: False

### $XONSH_DEBUG

Sets the xonsh debugging level. This may be an integer or a boolean. Setting it to `1` will get some basic information like input transformation, command replacement. With `2` or a higher number will make more debugging information presented, like PLY parsing messages.

configurable: False

default: 0

store_as_str: False

### $XONSH_DEBUG_BREAKPOINT_ENGINE

Default engine used by `@.debug.breakpoint()` when called without an explicit `engine=` argument. One of `'auto'`, `'pdbp'`, `'ipdb'`, `'pdb'`, `'eval'`. When set to `'auto'`, the first importable debugger is used, in priority order `pdbp` -> `ipdb` -> `pdb`, falling back to the `'eval'` REPL if none are available.

configurable: True

default: ‘auto’

store_as_str: False

### $XONSH_ENCODING

This is the encoding that xonsh should use for subprocess operations.

configurable: True

default: `sys.getdefaultencoding()`

store_as_str: False

### $XONSH_ENCODING_ERRORS

The flag for how to handle encoding errors should they happen. Any string flag that has been previously registered with Python is allowed. See the ‘Python codecs documentation’ (https://docs.python.org/3/library/codecs.html#error-handlers) for more information and available options.

configurable: True

default: `surrogateescape`

store_as_str: False

### $XONSH_ENV_PATTERN_DIRS

Pattern rule: env vars matching this regex are treated as env_path.

configurable: True

default: xonsh.environ.VarPattern(’\w*DIRS$’, ‘env_path’)

store_as_str: False

### $XONSH_ENV_PATTERN_PATH

Pattern rule: env vars matching this regex are treated as env_path.

configurable: True

default: xonsh.environ.VarPattern(’\w*PATH$’, ‘env_path’)

store_as_str: False

### $XONSH_INTERACTIVE

`True` if xonsh is running interactively, and `False` otherwise. It’s highly recommended to use this variable in your `xonshrc` files to split the code execution for interactive and non-interactive modes.

configurable: False

default: True

store_as_str: False

### $XONSH_LOGIN

`True` if xonsh is running as a login shell, and `False` otherwise.

configurable: False

default: False

store_as_str: False

### $XONSH_MODE

A string value representing the current xonsh execution mode: `interactive`, `script_from_file`, `source`, `single_command`, `script_from_stdin`. Note! This variable reflects the mode at start time (e.g. `script_from_file`) or code execution (e.g. `source`). If you need to gate behavior in an RC file that you plan to `source`, use `$XONSH_INTERACTIVE` as the flag instead.

configurable: True

default: ‘interactive’

store_as_str: False

### $XONSH_ORIGIN_ENV_FILE

The path to the file where environment variables are saved when running `xonsh --save-origin-env`. When xonsh `--load-origin-env` is executed, this file is used as the basis for the environment. Thus, from an existing xonsh session, you can start a new one with the same environment variables that were used when launching the original session.

configurable: True

default: not defined

store_as_str: False

### $XONSH_SOURCE

When running a xonsh script, this variable contains the absolute path to the currently executing script’s file.

configurable: False

default: ‘’

store_as_str: False

### $XONSH_STORE_STDIN

Whether or not to store the stdin that is supplied to the `!()` and `![]` operators.

configurable: True

default: False

store_as_str: False

### $XONSH_STYLE_OVERRIDES

A dictionary containing custom prompt_toolkit/pygments style definitions. The following style definitions are supported:

- `pygments.token.Token` - `$XONSH_STYLE_OVERRIDES[Token.Keyword] = '#ff0000'`

- pygments token name (string) - `$XONSH_STYLE_OVERRIDES['Token.Keyword'] = '#ff0000'`

- ptk style name (string) - `$XONSH_STYLE_OVERRIDES['pygments.keyword'] = '#ff0000'`

(The rules above all have the same effect.)

configurable: True

default: {}

store_as_str: False

### $XONSH_SYS_CONFIG_DIR

This is the location where xonsh system-level configuration information is stored.

configurable: False

default: On Linux & macOS: `'/etc/xonsh'` On Windows: `'%ALLUSERSPROFILE%\\xonsh'`

store_as_str: False

## Subprocess Settings

### $LAST_RETURN_CODE

Integer return code of the last command. Only updated during interactive use, i.e. not during execution of scripts.

configurable: True

default: 0

store_as_str: False

### $THREAD_SUBPROCS

Note: The `$XONSH_CAPTURE_ALWAYS` variable introduces finer control and you should probably use that instead.

Whether or not to try to run subprocess mode in a Python thread, when trying to capture its output. There are various trade-offs.

If True, xonsh is able capture & store the stdin, stdout, and stderr of threadable subprocesses. The disadvantages are listed in `$XONSH_CAPTURE_ALWAYS`. The desired effect is often up to the command, user, or use case.

None values are for internal use only and are used to turn off threading when loading xonshrc files. This is done because Bash was automatically placing new xonsh instances in the background at startup when threadable subprocs were used. Please see https://github.com/xonsh/xonsh/pull/3705 for more information.

configurable: True

default: True

store_as_str: False

### $XONSH_APPEND_NEWLINE

Append new line when a partial line is preserved in output.

configurable: True

default: `$XONSH_INTERACTIVE`

store_as_str: False

### $XONSH_BUILTINS_TO_CMD

If True, Python builtin names (e.g. `dir`, `zip`, `type`) will be executed as a subprocess command when a matching alias or executable exists. Covers two cases that otherwise run as Python and may fail or return surprising values: (1) a bare builtin name typed as a standalone expression (`zip` → run the `zip` command); (2) a builtin name followed by flag-looking arguments that also parses as a valid Python `BinOp` expression (`zip --help`, `id -a`). Otherwise the Python builtin value is returned as usual.

configurable: True

default: False

store_as_str: False

### $XONSH_CAPTURE_ALWAYS

Try to capture output of commands run without explicit capturing. If True, xonsh will capture the output of commands run directly or in `![]` to the session history. Setting to True has the following disadvantages: * Some interactive commands won’t work properly (like when `git` invokes an interactive editor).

> For more information see discussion at https://github.com/xonsh/xonsh/issues/3672.

- Stopping these commands with ^Z (i.e. `SIGTSTP`) is disabled as it causes deadlocked terminals. `SIGTSTP` may still be issued and only the physical pressing of `Ctrl+Z` is ignored.

Regardless of this value, commands run in `$()`, `!()` or with an IO redirection (`>` or `|`) will always be captured. Setting this to True depends on `$THREAD_SUBPROCS` being True.

configurable: True

default: False

store_as_str: False

### $XONSH_PROC_FREQUENCY

The process frequency is the time that xonsh process threads sleep for while running command pipelines. The value has units of seconds [s].

configurable: True

default: 0.0001

store_as_str: False

### $XONSH_SUBPROC_CAPTURED_PRINT_STDERR

If `True` the stderr from captured subproc will be printed automatically.

configurable: True

default: False

store_as_str: False

### $XONSH_SUBPROC_CMD_RAISE_ERROR

Whether or not to raise an error if a subprocess (captured or uncaptured) returns a non-zero exit status, which indicates failure. This is most useful in xonsh scripts or modules where failures should cause an end to execution. This is less useful at a terminal. The error that is raised is a `subprocess.CalledProcessError`. (Replaces the deprecated `$RAISE_SUBPROC_ERROR`.)

configurable: True

default: False

store_as_str: False

### $XONSH_SUBPROC_OUTPUT_FORMAT

Set output format for subprocess e.g. `du $(ls)`. By default (`stream_lines`) subprocess operator returns text output. Set `list_lines` to have list of lines.

configurable: True

default: ‘stream_lines’

store_as_str: False

### $XONSH_SUBPROC_RAISE_ERROR

Whether or not to raise an error when the final command of a logical chain (`cmd1 && cmd2` / `cmd1 || cmd2`) returns a non-zero exit status. Unlike `$XONSH_SUBPROC_CMD_RAISE_ERROR` (which raises on every individual non-zero subprocess), commands inside a logical chain do not raise on their own — only the result of the whole short-circuit evaluation is checked. Examples (with the default `True`):

- `echo 1 && echo 2` — last executed is `echo 2` (rc=0): no raise.

- `ls nono || echo 1` — last executed is `echo 1` (rc=0): no raise.

- `ls nono && echo 1` — last executed is `ls nono` (rc≠0): raises.

- `(echo 1 && ls /etc) || echo 1` — last executed is `ls /etc` (rc=0): no raise.

The exception raised is a `subprocess.CalledProcessError`.

configurable: True

default: True

store_as_str: False

### $XONSH_SUBPROC_TRACE

Set to `True` or `1` to show arguments list of every executed subprocess command. Use `2` to have a specification. Use `3` to have full specification. Alternatively assign a callable `f(cmds, captured=..., specs=...)` to format the trace output yourself — it is invoked instead of the default printer. `specs` is the list of `SubprocSpec` objects about to be executed; `CommandPipeline` is not yet built at this point.

configurable: True

default: By default it just prints `cmds` like below.

    def _tracer(cmds, captured, specs):
        # ``specs`` is a list of SubprocSpec — use e.g. ``s.args``,
        # ``s.alias``, ``s.binary_loc``, ``s.threadable`` for details.
        print(f"TRACE SUBPROC: {cmds}, captured={captured}", file=sys.stderr)

    $XONSH_SUBPROC_TRACE = _tracer

store_as_str: False

## Error Handling Settings

### $XONSH_SHOW_TRACEBACK

Controls if a traceback is shown if exceptions occur in the shell. Set to `True` to always show traceback or `False` to always hide. If undefined then the traceback is hidden but a notice is shown on how to enable the full traceback.

configurable: True

default: False

store_as_str: False

### $XONSH_TRACEBACK_LOGFILE

Specifies a file to store the traceback log to, regardless of whether `XONSH_SHOW_TRACEBACK` has been set. Its value must be a writable file or None / the empty string if traceback logging is not desired. Logging to a file is not enabled by default.

configurable: True

default: None

store_as_str: False

## Jobs Settings

### $AUTO_CONTINUE

If `True`, automatically resume stopped jobs when they are disowned. When stopped jobs are disowned and this option is `False`, a warning will print information about how to continue the stopped process.

configurable: True

default: False

store_as_str: False

## Language and locale settings.

### $LANG

Fallback locale setting for systems where it matters.

configurable: True

default: ‘C.UTF-8’

store_as_str: False

### $LC_COLLATE

configurable: True

default: ‘C.UTF-8’

store_as_str: False

### $LC_CTYPE

configurable: True

default: ‘C.UTF-8’

store_as_str: False

### $LC_MESSAGES

configurable: True

default: ‘C.UTF-8’

store_as_str: False

### $LC_MONETARY

configurable: True

default: ‘C.UTF-8’

store_as_str: False

### $LC_NUMERIC

configurable: True

default: ‘C.UTF-8’

store_as_str: False

### $LC_TIME

configurable: True

default: ‘C.UTF-8’

store_as_str: False

### $XONSH_DATETIME_FORMAT

The format that is used for `datetime.strptime()` in various places, i.e the history timestamp option.

configurable: True

default: ‘%Y-%m-%d %H:%M’

store_as_str: False

## Cache Settings

### $COMMANDS_CACHE_SAVE_INTERMEDIATE

If enabled, the CommandsCache is saved between runs and can reduce the startup time.

configurable: True

default: False

store_as_str: False

### $ENABLE_COMMANDS_CACHE

Command names in a directory are cached when enabled. On some platforms it may not be accurate enough (e.g. Windows, Linux save mtime in seconds). Setting it to False would disable the caching mechanism and may slow down the shell.

configurable: True

default: True

store_as_str: False

### $XONSH_CACHE_DIR

This is the location where cache files used by xonsh are stored, such as commands-cache…

configurable: True

default: `$XDG_CACHE_HOME/xonsh`

store_as_str: False

### $XONSH_CACHE_EVERYTHING

Controls whether all code (including code entered at the interactive prompt) will be cached.

configurable: True

default: False

store_as_str: False

### $XONSH_CACHE_SCRIPTS

Controls whether the code for scripts run from xonsh will be cached (`True`) or re-compiled each time (`False`).

configurable: True

default: True

store_as_str: False

### $XONSH_COMMANDS_CACHE_READ_DIR_ONCE

List of directory prefixes whose contents are cached on first access and never re-read within the session. Any `$PATH` entry that starts with one of these prefixes (or is a subdirectory) will have its file listing cached. This helps on systems with I/O lag, network drives, and similar issues. On Windows this defaults to `['C:\\Windows']` (via `%WINDIR%`). On WSL it auto-detects `/mnt/*/Windows` directories. On Linux/Mac it is empty by default but can be extended (e.g. `$XONSH_COMMANDS_CACHE_READ_DIR_ONCE += ['/bin', '/sbin']`).

configurable: True

default: []

store_as_str: False

### $XONSH_COMMANDS_CACHE_TRACE

If True, print trace messages showing where each command was resolved from (cached directory listing XONSH_COMMANDS_CACHE_READ_DIR_ONCE vs. disk stat) and how long it took.

configurable: True

default: False

store_as_str: False

## `cd` Behavior

### $AUTO_CD

Flag to enable changing to a directory by entering the dirname or full path only (without the cd command).

configurable: True

default: False

store_as_str: False

### $AUTO_PUSHD

Flag for automatically pushing directories onto the directory stack.

configurable: True

default: False

store_as_str: False

### $CDPATH

A list of paths to be used as roots for a cd, breaking compatibility with Bash, xonsh always prefer an existing relative path.

configurable: True

default: ()

store_as_str: False

### $COMPLETE_DOTS

Flag to specify how current and previous directories should be tab completed (`./`, `../`):

- `always` - Always complete paths with `./` and `../`

- `never` - Never complete paths with `./` and `../`

- `matching` - Complete if path starts with `.` or `..`

configurable: True

default: ‘matching’

store_as_str: False

### $DIRSTACK_SIZE

Maximum size of the directory stack.

configurable: True

default: 20

store_as_str: False

### $PUSHD_MINUS

Flag for directory pushing functionality. False is the normal behavior.

configurable: True

default: False

store_as_str: False

### $PUSHD_SILENT

Whether or not to suppress directory stack manipulation output.

configurable: True

default: False

store_as_str: False

## Interpreter Behavior

### $DOTGLOB

Globbing files with `*` or `**` will also match dotfiles, or those hidden files whose names begin with a literal `.`. Such files are filtered out by default.

configurable: True

default: False

store_as_str: False

### $EXPAND_ENV_VARS

Toggles whether environment variables are expanded inside of strings in subprocess mode.

configurable: True

default: True

store_as_str: False

### $FOREIGN_ALIASES_OVERRIDE

Whether or not foreign aliases should override xonsh aliases with the same name. Note that setting of this must happen in the environment that xonsh was started from. It cannot be set in the `.xonshrc` as loading of foreign aliases happens before `.xonshrc` is parsed.

configurable: True

default: False

store_as_str: False

### $FOREIGN_ALIASES_SUPPRESS_SKIP_MESSAGE

Whether or not foreign aliases should suppress the message that informs the user when a foreign alias has been skipped because it already exists in xonsh.

configurable: True

default: False

store_as_str: False

### $GLOB_SORTED

Toggles whether globbing results are manually sorted. If `False`, the results are returned in arbitrary order.

configurable: True

default: True

store_as_str: False

### $XONSH_SUBPROC_ARG_EXPANDUSER

If True, `~` and `~user` in subprocess arguments are expanded to home directories (e.g. `~/docs` → `/home/user/docs`, `~bob/docs` → `/home/bob/docs`). Set to False to pass `~` through as a literal character.

configurable: True

default: True

store_as_str: False

## Xontrib Settings

### $XONTRIBS_AUTOLOAD_DISABLED

Controls auto-loading behaviour of xontrib packages at the startup.

- Set this to `True` to disable autoloading completely.

- Setting this to a list of xontrib names will block loading those specifically.

configurable: True

default: Xontribs with `xonsh.xontrib` entrypoint will be loaded automatically by default.

store_as_str: False

## Interactive Prompt

### $BOTTOM_TOOLBAR

Template string for the bottom toolbar. This may be parametrized in the same way as the `$PROMPT` variable. Currently, this is only available in the prompt-toolkit shell.

configurable: True

default: ‘’

store_as_str: False

### $COLOR_INPUT

Flag for syntax highlighting interactive input.

configurable: True

default: True

store_as_str: False

### $COLOR_RESULTS

Flag for syntax highlighting return values.

configurable: True

default: True

store_as_str: False

### $DYNAMIC_CWD_ELISION_CHAR

The string used to show a shortened directory in a shortened cwd, e.g. `'…'`.

configurable: True

default: ‘’

store_as_str: False

### $DYNAMIC_CWD_WIDTH

Maximum length in number of characters or as a percentage for the `cwd` prompt variable. For example, “20” is a twenty character width and “10%” is ten percent of the number of columns available.

configurable: True

default: (inf, ‘c’)

store_as_str: False

### $IGNOREEOF

Prevents Ctrl-D from exiting the shell.

configurable: True

default: False

store_as_str: False

### $INDENT

Indentation string for multiline input

configurable: True

default: ‘ ‘

store_as_str: False

### $LS_COLORS

Color settings for `ls` command line utility and, with `$SHELL_TYPE='prompt_toolkit'`, file arguments in subprocess mode.

configurable: True

default: `*.7z=1;0;31:*.Z=1;0;31:*.aac=0;36:*.ace=1;0;31:*.alz=1;0;31:*.arc=1;0;31:*.arj=1;0;31:*.asf=1;0;35:*.au=0;36:*.avi=1;0;35:*.bmp=1;0;35:*.bz=1;0;31:*.bz2=1;0;31:*.cab=1;0;31:*.cgm=1;0;35:*.cpio=1;0;31:*.deb=1;0;31:*.dl=1;0;35:*.dwm=1;0;31:*.dz=1;0;31:*.ear=1;0;31:*.emf=1;0;35:*.esd=1;0;31:*.flac=0;36:*.flc=1;0;35:*.fli=1;0;35:*.flv=1;0;35:*.gif=1;0;35:*.gl=1;0;35:*.gz=1;0;31:*.jar=1;0;31:*.jpeg=1;0;35:*.jpg=1;0;35:*.lha=1;0;31:*.lrz=1;0;31:*.lz=1;0;31:*.lz4=1;0;31:*.lzh=1;0;31:*.lzma=1;0;31:*.lzo=1;0;31:*.m2v=1;0;35:*.m4a=0;36:*.m4v=1;0;35:*.mid=0;36:*.midi=0;36:*.mjpeg=1;0;35:*.mjpg=1;0;35:*.mka=0;36:*.mkv=1;0;35:*.mng=1;0;35:*.mov=1;0;35:*.mp3=0;36:*.mp4=1;0;35:*.mp4v=1;0;35:*.mpc=0;36:*.mpeg=1;0;35:*.mpg=1;0;35:*.nuv=1;0;35:*.oga=0;36:*.ogg=0;36:*.ogm=1;0;35:*.ogv=1;0;35:*.ogx=1;0;35:*.opus=0;36:*.pbm=1;0;35:*.pcx=1;0;35:*.pgm=1;0;35:*.png=1;0;35:*.ppm=1;0;35:*.qt=1;0;35:*.ra=0;36:*.rar=1;0;31:*.rm=1;0;35:*.rmvb=1;0;35:*.rpm=1;0;31:*.rz=1;0;31:*.sar=1;0;31:*.spx=0;36:*.svg=1;0;35:*.svgz=1;0;35:*.swm=1;0;31:*.t7z=1;0;31:*.tar=1;0;31:*.taz=1;0;31:*.tbz=1;0;31:*.tbz2=1;0;31:*.tga=1;0;35:*.tgz=1;0;31:*.tif=1;0;35:*.tiff=1;0;35:*.tlz=1;0;31:*.txz=1;0;31:*.tz=1;0;31:*.tzo=1;0;31:*.tzst=1;0;31:*.vob=1;0;35:*.war=1;0;31:*.wav=0;36:*.webm=1;0;35:*.wim=1;0;31:*.wmv=1;0;35:*.xbm=1;0;35:*.xcf=1;0;35:*.xpm=1;0;35:*.xspf=0;36:*.xwd=1;0;35:*.xz=1;0;31:*.yuv=1;0;35:*.z=1;0;31:*.zip=1;0;31:*.zoo=1;0;31:*.zst=1;0;31:bd=40;0;33:ca=0;30;41:cd=40;0;33:di=1;0;34:do=1;0;35:ex=1;0;32:ln=1;0;36:mh=0:mi=0:or=40;0;31:ow=0;34;42:pi=40;0;33:rs=0:sg=0;30;43:so=1;0;35:st=0;37;44:su=0;37;41:tw=0;30;42`

store_as_str: False

### $MULTILINE_PROMPT

Prompt text for 2nd+ lines of input, may be str or function which returns a str.

configurable: True

default: ‘ ‘

store_as_str: False

### $MULTILINE_PROMPT_POS

Indicator inserted after the line continuation marks set in `$MULTILINE_PROMPT`. Can be used to mark the end of a semantic continuation prompt and the beginning of user input (see Semantic Prompts or WezTerm for more details). May be str or function which returns a str.

configurable: True

default: not defined

store_as_str: False

### $MULTILINE_PROMPT_PRE

Indicator inserted before the line continuation marks set in `$MULTILINE_PROMPT`. Can be used to mark the start of a semantic continuation prompt (see Semantic Prompts or WezTerm for more details). May be str or function which returns a str.

configurable: True

default: not defined

store_as_str: False

### $PRETTY_PRINT_RESULTS

Flag for “pretty printing” return values.

configurable: True

default: True

store_as_str: False

### $PROMPT

The prompt text. May contain keyword arguments which are auto-formatted, see ‘Customizing the Prompt’ at http://xon.sh/tutorial.html#customizing-the-prompt. This value is never inherited from parent processes.

configurable: True

default: `xonsh.environ.DEFAULT_PROMPT`

store_as_str: False

### $PROMPT_FIELDS

Dictionary containing variables to be used when formatting `$PROMPT` and `$TITLE`. See ‘Customizing the Prompt’ http://xon.sh/tutorial.html#customizing-the-prompt.

configurable: False

default: `xonsh.prompt.base.PromptFields`

store_as_str: False

### $PROMPT_REFRESH_INTERVAL

Interval (in seconds) to evaluate and update `$PROMPT`, `$RIGHT_PROMPT` and `$BOTTOM_TOOLBAR`. The default is zero (no update). NOTE: `$UPDATE_PROMPT_ON_KEYPRESS` must be set to `True` for this variable to take effect.

configurable: True

default: 0.0

store_as_str: False

### $PROMPT_TOKENS_FORMATTER

Final processor that receives all tokens in the prompt template. It gives option to format the prompt with different prefix based on other tokens values. Highly useful for implementing something like powerline theme.

configurable: True

default: `xonsh.prompt.base.prompt_tokens_formatter_default`

store_as_str: False

### $RIGHT_PROMPT

Template string for right-aligned text at the prompt. This may be parametrized in the same way as the `$PROMPT` variable. Currently, this is only available in the prompt-toolkit shell.

configurable: True

default: ‘’

store_as_str: False

### $SHELL_TYPE

Which shell is used. Currently two base shell types are supported:

- `readline` - backed by Python’s readline module

- `prompt_toolkit` - uses external library of the same name

- `random` - selects a random shell from the above on startup

- `best` - selects the most feature-rich shell available on the user’s system

To use the `prompt_toolkit` shell you need to have the prompt_toolkit library installed. To specify which shell should be used, do so in the run control file. It also accepts a class type that inherits from `xonsh.shells.base_shell.BaseShell`.

configurable: True

default: `best`

store_as_str: False

### $SUGGEST_COMMANDS

When a user types an invalid command, xonsh will try to offer suggestions of similar valid commands if this is True.

configurable: True

default: True

store_as_str: False

### $SUGGEST_MAX_NUM

xonsh will show at most this many suggestions in response to an invalid command. If negative, there is no limit to how many suggestions are shown.

configurable: True

default: 5

store_as_str: False

### $SUGGEST_THRESHOLD

An error threshold. If the Levenshtein distance between the entered command and a valid command is less than this value, the valid command will be offered as a suggestion. Also used for “fuzzy” tab completion of paths.

configurable: True

default: 3

store_as_str: False

### $SUPPRESS_BRANCH_TIMEOUT_MESSAGE

Whether or not to suppress branch timeout warning messages when getting {gitstatus} PROMPT_FIELD.

configurable: True

default: False

store_as_str: False

### $TITLE

The title text for the window in which xonsh is running. Formatted in the same manner as `$PROMPT`, see ‘Customizing the Prompt’ http://xon.sh/tutorial.html#customizing-the-prompt.

configurable: True

default: `xonsh.environ.DEFAULT_TITLE`

store_as_str: False

### $UPDATE_PROMPT_ON_KEYPRESS

Disables caching the prompt between commands, so that it would be reevaluated on each keypress. Disabled by default because of the incurred performance penalty.

configurable: True

default: False

store_as_str: False

### $VC_BRANCH_TIMEOUT

The timeout (in seconds) for version control branch computations. This is a timeout per subprocess call, so the total time to compute will be larger than this in many cases.

configurable: True

default: 0.1

store_as_str: False

### $VC_GIT_INCLUDE_UNTRACKED

Whether or not untracked file changes should count as ‘dirty’ in git.

configurable: True

default: False

store_as_str: False

### $VC_HG_SHOW_BRANCH

Whether or not to show the Mercurial branch in the prompt.

configurable: True

default: True

store_as_str: False

### $VIRTUAL_ENV

Path to the currently active Python environment.

configurable: False

default: not defined

store_as_str: False

### $XONSH_HISTORY_MATCH_ANYWHERE

When searching history from a partial string (by pressing up arrow), match command history anywhere in a given line (not just the start).

configurable: True

default: False

store_as_str: False

### $XONSH_PROMPT_SHOW_SUBPROC_ERROR

Whether the interactive prompt should display the `subprocess.CalledProcessError` message when a command at the prompt fails. The failing command’s own `stderr` is always shown — this flag only controls xonsh’s own exception printout that follows it.

- `False` (default): after a failing command the prompt returns silently; the command’s `stderr` is still visible and `$LAST_RETURN_CODE` is set.

- `True`: xonsh additionally prints `subprocess.CalledProcessError: Command '...' returned non-zero exit status N.`.

Notes:

- Per-command `@error_raise` decorator always shows the exception, regardless of this flag.

- Non-interactive scripts (run via `./script.xsh` or `xonsh -c`) are unaffected — there the exception propagates normally so the failure is visible.

configurable: True

default: False

store_as_str: False

### $XONSH_STDERR_POSTFIX

A format string, using the same keys and colors as `$PROMPT`, that is appended whenever stderr is displayed. This may be used in conjunction with `$XONSH_STDERR_PREFIX` to start the block. For example, to have stderr appear on a red background, the prefix & postfix pair would be “{BACKGROUND_RED}” & “{RESET}”. It works with `!()` (colors will be reduced) or `$XONSH_CAPTURE_ALWAYS=True`.

configurable: True

default: ‘’

store_as_str: False

### $XONSH_STDERR_PREFIX

A format string, using the same keys and colors as `$PROMPT`, that is prepended whenever stderr is displayed. This may be used in conjunction with `$XONSH_STDERR_POSTFIX` to close out the block. For example, to have stderr appear on a red background, the prefix & postfix pair would be “{BACKGROUND_RED}” & “{RESET}”. It works with `!()` (colors will be reduced) or `$XONSH_CAPTURE_ALWAYS=True`.

configurable: True

default: ‘’

store_as_str: False

### $XONSH_SUPPRESS_WELCOME

Suppresses the welcome message.

configurable: True

default: False

store_as_str: False

#### Prompt Toolkit shell

Only usable with `$SHELL_TYPE=prompt_toolkit.`

### $AUTO_SUGGEST_IN_COMPLETIONS

Places the auto-suggest result as the first option in the completions. This enables you to tab complete the auto-suggestion.

configurable: True

default: False

store_as_str: False

### $MOUSE_SUPPORT

Enable mouse support in the `prompt_toolkit` shell. This allows clicking for positioning the cursor or selecting a completion. In some terminals however, this disables the ability to scroll back through the history of the terminal. Only usable with `$SHELL_TYPE=prompt_toolkit`

configurable: True

default: False

store_as_str: False

### $PROMPT_TOOLKIT_COLOR_DEPTH

The color depth used by prompt toolkit 2. Possible values are: `DEPTH_1_BIT`, `DEPTH_4_BIT`, `DEPTH_8_BIT`, `DEPTH_24_BIT` colors. Default is an empty string which means that prompt toolkit decide.

configurable: True

default: ‘’

store_as_str: False

### $PTK_STYLE_OVERRIDES

A dictionary containing custom prompt_toolkit style definitions. (deprecated)

configurable: True

default: {}

store_as_str: False

### $VI_MODE

Flag to enable `vi_mode` in the `prompt_toolkit` shell.

configurable: True

default: False

store_as_str: False

### $XONSH_AUTOPAIR

Whether Xonsh will auto-insert matching parentheses, brackets, and quotes. Only available under the prompt-toolkit shell.

configurable: True

default: False

store_as_str: False

### $XONSH_COPY_ON_DELETE

Whether to copy words/lines to clipboard on deletion (must be set in the run control file). Does not have any effect in `vi_mode`. Only available under the prompt-toolkit shell.

configurable: True

default: False

store_as_str: False

### $XONSH_CTRL_BKSP_DELETION

Delete a word on CTRL-Backspace (like ALT-Backspace). This will only work when your terminal emulator sends `\x7f` on backspace and `\x08` on CTRL-Backspace (which is configurable on most terminal emulators). On windows, the keys are reversed.

configurable: True

default: False

store_as_str: False

### $XONSH_PROMPT_AUTO_SUGGEST

Enable automatic command suggestions based on history.

Pressing the right arrow key inserts the currently displayed suggestion. Set before starting the prompt e.g. in `.xonshrc` file.

configurable: True

default: True

store_as_str: False

### $XONSH_PROMPT_CURSOR_SHAPE

The cursor shape. Possible values for prompt toolkit are: `block`, `beam`, `underline`, `blinking-block`, `blinking-beam`, `blinking-underline`, `modal`, `modal-vi-mode-only`, `never-change`. Default value is `modal-vi-mode-only` which means `modal` if in vi mode and `never-change` if not in vi mode.

configurable: True

default: modal-vi-mode-only

store_as_str: False

### $XONSH_PROMPT_NEXT_CMD

The text of the next command that will be inserted in the next prompt. Use `<cursor>` marker to set the cursor position, e.g. `$XONSH_PROMPT_NEXT_CMD = 'echo <cursor> world'`.

configurable: True

default: ‘’

store_as_str: False

### $XONSH_PROMPT_NEXT_CMD_SUGGESTION

The text of the next command suggestion that will be inserted in the next prompt.

configurable: True

default: ‘’

store_as_str: False

### $XONSH_USE_SYSTEM_CLIPBOARD

Whether to let the shell use the system clipboard (must be set in the run control file). The main use-case is to fully disable clipboard integration in `vi_mode`. Only available under the prompt-toolkit shell.

configurable: True

default: True

store_as_str: False

### Asynchronous Prompt

Load `$PROMPT` in background without blocking read-eval loop.

### $ASYNC_INVALIDATE_INTERVAL

When ENABLE_ASYNC_PROMPT is True, it may call the redraw frequently. This is to group such calls into one that happens within that timeframe. The number is set in seconds.

configurable: True

default: 0.05

store_as_str: False

### $ASYNC_PROMPT_THREAD_WORKERS

Define the number of workers used by the ASYNC_PROMPT’s pool. By default it is the same as defined by Python’s concurrent.futures.ThreadPoolExecutor class.

configurable: True

default: None

store_as_str: False

### $ENABLE_ASYNC_PROMPT

When enabled the prompt is rendered using threads. `$PROMPT_FIELDS` that take long will be updated in the background and will not affect prompt speed.

configurable: True

default: False

store_as_str: False

## Interactive Prompt History

### $HISTCONTROL

A set of strings (comma-separated list in string form) of options that determine what commands are saved to the history list. By default all commands are saved. Options are as follows:

- `ignoredups` will not save the command if it matches the previous command

- `ignoreerr` will cause any commands that fail (i.e. return non-zero exit status) to not be added to the history list

- `ignorespace` will not save the command if it begins with a space

configurable: True

default: set()

store_as_str: True

### $XONSH_HISTORY_BACKEND

Set which history backend to use. Options are: ‘json’, ‘sqlite’, and ‘dummy’. The default is ‘json’. `XONSH_HISTORY_BACKEND` also accepts a class type that inherits from `xonsh.history.base.History`, or its instance.

configurable: True

default: ‘json’

store_as_str: False

### $XONSH_HISTORY_FILE

Location of history file set by history backend (default) or set by the user.

configurable: False

default: None

store_as_str: False

### $XONSH_HISTORY_IGNORE_REGEX

Set a filter criteria for history items using a regular expression. Any matching items will not be retained in the history. Example: `$XONSH_HISTORY_IGNORE_REGEX = '(^echo|^.*\#\#\#\s*|.*\#\#\#\s*$)'` - skip commands that start from `echo` or `###`, or end from `###`.

configurable: True

default: None

store_as_str: False

### $XONSH_HISTORY_SAVE_CWD

Save current working directory to the history.

configurable: True

default: True

store_as_str: False

### $XONSH_HISTORY_SIGINT_FLUSH

Save history after getting SIGINT (Ctrl+C).

configurable: True

default: True

store_as_str: False

### $XONSH_HISTORY_SIZE

Value and units tuple that sets the size of history after garbage collection. Canonical units are:

- `commands` for the number of past commands executed,

- `files` for the number of history files to keep,

- `s` for the number of seconds in the past that are allowed, and

- `b` for the number of bytes that history may consume.

Common abbreviations, such as ‘6 months’ or ‘1 GB’ are also allowed.

configurable: True

default: `(8128, 'commands')` or `'8128 commands'`

store_as_str: False

### $XONSH_STORE_STDOUT

Store the `stdout` and `stderr` streams to the history. Requires that XONSH_CAPTURE_ALWAYS is True.

configurable: True

default: False

store_as_str: False

## Tab-completion behavior.

### $ALIAS_COMPLETIONS_OPTIONS_BY_DEFAULT

If True, `xonsh.completers.argparser.ArgparseCompleter` based completions will show options (e.g. `--help`) without requesting explicitly with option prefix `-`.

configurable: True

default: False

store_as_str: False

### $ALIAS_COMPLETIONS_OPTIONS_LONGEST

Whether to show all options or just the longest for the `xonsh.completers.argparser.ArgparseCompleter` based completions. For example, with `-h`, `--help` both denoting `help` action. If True, then only `--help` is shown. This is to reduce the noise in generated completions.

configurable: True

default: False

store_as_str: False

### $BASH_COMPLETIONS

This is a list (or tuple) of strings that specifies where the `bash_completion` script and supplemental completion scripts may be found. The first valid `bash_completion` framework file will be used; non-framework files and files in directories are sourced after it. For better performance, bash-completion v2.x is recommended since it lazy-loads individual completion scripts. For both bash-completion v1.x and v2.x, paths of package-managed individual completion scripts (like `.../completes/ssh`) do not need to be included here. The default values are platform dependent, but reasonable. To specify an alternate list, do so in the run control file.

configurable: True

default: Platform-dependent. The list probes every known install prefix for the bash-completion framework script and the first existing framework file is sourced, followed by supplemental user completion scripts:

- Linux / Cygwin / MSYS — the standard FHS path `/usr/share/bash-completion/bash_completion`, plus Linuxbrew (`/home/linuxbrew/.linuxbrew/...`), Nix (`/run/current-system/sw/...`, `~/.nix-profile/...`), and `~/.bash_completions`.

- macOS — Homebrew on Intel (`/usr/local/...`) and Apple Silicon (`/opt/homebrew/...`), MacPorts (`/opt/local/...`), `~/.bash_completions`, and Nix.

- BSD — `/usr/local/...`, `/usr/pkg/...` (pkgsrc), and `~/.bash_completions`.

- Windows — Git for Windows installation prefix (both bash-completion and the bundled `git-completion.bash`).

Each entry covers both v1.x and v2.x of bash-completion where applicable; v2.x is preferred for performance (lazy per-command loading).

store_as_str: False

### $CMD_COMPLETIONS_SHOW_DESC

If True, command completions will show description part with path to the binary and alias in case of xonsh functions.

configurable: True

default: False

store_as_str: False

### $COMPLETIONS_BRACKETS

Flag to enable/disable inclusion of square brackets and parentheses in Python attribute completions.

configurable: True

default: True

store_as_str: False

### $COMPLETION_QUERY_LIMIT

Maximum number of completions to collect. In prompt_toolkit the list is truncated at this value and a notice is shown above the prompt; in readline the user is asked ‘Display all N possibilities?’.

configurable: True

default: 1000

store_as_str: False

### $FUZZY_PATH_COMPLETION

Toggles ‘fuzzy’ matching of paths for tab completion, which is only used as a fallback if no other completions succeed but can be used as a way to adjust for typographical errors. If `True`, then, e.g., `xonhs` will match `xonsh`.

configurable: True

default: True

store_as_str: False

### $SUBSEQUENCE_PATH_COMPLETION

Toggles subsequence matching of paths for tab completion. If `True`, then, e.g., `~/u/ro` can match `~/lou/carcolh`.

configurable: True

default: True

store_as_str: False

### $XONSH_BASH_PATH_OVERRIDE

Override the path used to call bash externally. This allows a user to choose which bash executable to call for `source-bash` and any bash completions that are configured. This variable overrides the default settings in `xonsh.platform.bash_command`.

configurable: True

default: None

store_as_str: False

### $XONSH_COMPLETER_DIRS

A list of paths where Xonsh searches for command completions. Any completions defined are lazy loaded when needed. The name of the completer file should match that of the completing command. The file should contain a function with the signature `xonsh_complete(ctx: CommandContext) -> Iterator[RichCompletion|str]`.

configurable: True

default: By default, the following paths are searched. 1. `$XONSH_CONFIG_DIR/completions` - user level completions 2. `$XONSH_SYS_CONFIG_DIR/completions` - system level completions 3. `$XONSH_DATA_DIR/generated_completions` - auto generated completers from man pages 4. `$XDG_DATA_DIRS/xonsh/vendor_completions` - completers from other programs can be placed here.

Other than this, Python package namespace `xompletions` can be used to put completer modules as well.

store_as_str: False

### $XONSH_COMPLETER_EMOJI_PREFIX

Trigger prefix for colorful emoji completion. Set to `'::'` to enable, then type `::<TAB>` or `::cat<TAB>` to search. Default is `None` (disabled).

configurable: True

default: None

store_as_str: False

### $XONSH_COMPLETER_MODE

Controls how completions are filtered.

`'substring_tier'` (default) — shows all completions that contain the typed text as a substring, ranked in tiers from best to worst match:

> 1. Exact prefix (`test` matches `test_foo`)

> 2. Case-insensitive prefix (`test` matches `TEST_FOO`)

> 3. Substring (`test` matches `my_test_bar`)

> 4. Case-insensitive substring (`test` matches `MY_TEST_BAR`)

Within each tier, results are sorted by the position of the match, then alphabetically. This gives a natural ranking where the best matches appear first while still showing all possibilities.

`'prefix'` — shows only completions that start with the typed text (case-insensitive). Substring matches are hidden.

configurable: True

default: ‘substring_tier’

store_as_str: False

### $XONSH_COMPLETER_SYMBOLS_PREFIX

Trigger prefix for unicode symbol completion. Set to `':::'` to enable, then type `:::<TAB>` or `:::arrow<TAB>` to search. Default is `None` (disabled).

configurable: True

default: None

store_as_str: False

### $XONSH_COMPLETER_TRACE

Set to `True` to show completers invoked and their return values. Each completion is printed on its own line with its `source` completer and any non-default `RichCompletion` attributes.

configurable: True

default: False

store_as_str: False

#### Prompt Toolkit tab-completion

### $COMPLETIONS_CONFIRM

While tab-completions menu is displayed, press <Enter> to confirm completion instead of running command. This only affects the prompt-toolkit shell.

configurable: True

default: True

store_as_str: False

### $COMPLETIONS_DISPLAY

Configure if and how Python completions are displayed by the `prompt_toolkit` shell.

This option does not affect Bash completions, auto-suggestions, etc.

Changing it at runtime will take immediate effect, so you can quickly disable and enable completions during shell sessions.

- If `$COMPLETIONS_DISPLAY` is `none` or `false`, do not display those completions.

- If `$COMPLETIONS_DISPLAY` is `single`, display completions in a single column while typing.

- If `$COMPLETIONS_DISPLAY` is `multi` or `true`, display completions in multiple columns while typing.

- If `$COMPLETIONS_DISPLAY` is `readline`, display completions will emulate the behavior of readline.

These option values are not case- or type-sensitive, so e.g. writing `$COMPLETIONS_DISPLAY = None` and `$COMPLETIONS_DISPLAY = 'none'` are equivalent. Only usable with `$SHELL_TYPE=prompt_toolkit`

configurable: True

default: ‘multi’

store_as_str: False

### $COMPLETIONS_MENU_ROWS

Number of rows to reserve for tab-completions menu if `$COMPLETIONS_DISPLAY` is `single` or `multi`. This only affects the prompt-toolkit shell.

configurable: True

default: 5

store_as_str: False

### $COMPLETION_IN_THREAD

When generating the completions takes time, it’s better to do this in a background thread. When this is True, background threads is used for completion.

configurable: True

default: False

store_as_str: False

### $COMPLETION_MODE

Mode of tab completion in prompt-toolkit shell (only).

‘default’, the default, selects the common prefix of completions on first TAB, then cycles through all completions. ‘menu-complete’ selects the first whole completion on the first TAB, then cycles through the remaining completions, then the common prefix.

configurable: True

default: ‘default’

store_as_str: False

### $UPDATE_COMPLETIONS_ON_KEYPRESS

Completions display is evaluated and presented whenever a key is pressed. This avoids the need to press TAB, except to cycle through the possibilities. This currently only affects the prompt-toolkit shell.

configurable: True

default: False

store_as_str: False

## Windows OS

### $ANSICON

This is used on Windows to set the title, if available.

configurable: False

default: not defined

store_as_str: False

### $FORCE_POSIX_PATHS

Forces forward slashes (`/`) on Windows systems when using auto completion if set to anything truthy.

configurable: False

default: False

store_as_str: False

### $INTENSIFY_COLORS_ON_WIN

Enhance style colors for readability when using the default terminal (`cmd.exe`) on Windows. Blue colors, which are hard to read, are replaced with cyan. Other colors are generally replaced by their bright counter parts.

configurable: False

default: True

store_as_str: False

### $XONSH_WIN_CONSOLE_HISTORY_BUFFERS

On Windows, number of console command-history buffers to reserve at startup (one per attached console process). The default of 4 is exhausted by nested consoles (xonsh -> `py` -> `python`), losing up-arrow history in the child REPL; `0` disables. For the other fields, set this to `0` and call `@.imp.xonsh.platforms.winutils.set_console_history_info(nbuf=64, bufsize=1024, flags=1)` from your xonsh RC.

configurable: False

default: 32

store_as_str: False

## Deprecated settings.

### $AUTO_SUGGEST

Deprecated. Use XONSH_PROMPT_AUTO_SUGGEST.

configurable: True

default: True

store_as_str: False

### $RAISE_SUBPROC_ERROR

Deprecated. Use XONSH_SUBPROC_CMD_RAISE_ERROR.

configurable: True

default: False

store_as_str: False