Environment Variables¶

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

General¶
$AUTO_CONTINUE	$COMMANDS_CACHE_SAVE_INTERMEDIATE	$COMMANDS_CACHE_SIZE_WARNING
$HOSTNAME	$HOSTTYPE	$LANG
$LC_COLLATE	$LC_CTYPE	$LC_MESSAGES
$LC_MONETARY	$LC_NUMERIC	$LC_TIME
$LOADED_RC_FILES	$OLDPWD	$PATH
$PATHEXT	$RAISE_SUBPROC_ERROR	$TERM
$THREAD_SUBPROCS	$UPDATE_OS_ENVIRON	$XDG_CONFIG_HOME
$XDG_DATA_HOME	$XONSHRC	$XONSHRC_DIR
$XONSH_APPEND_NEWLINE	$XONSH_CACHE_EVERYTHING	$XONSH_CACHE_SCRIPTS
$XONSH_CAPTURE_ALWAYS	$XONSH_COLOR_STYLE	$XONSH_CONFIG_DIR
$XONSH_DATA_DIR	$XONSH_DATETIME_FORMAT	$XONSH_DEBUG
$XONSH_ENCODING	$XONSH_ENCODING_ERRORS	$XONSH_INTERACTIVE
$XONSH_LOGIN	$XONSH_NO_AMALGAMATE	$XONSH_PROC_FREQUENCY
$XONSH_SHOW_TRACEBACK	$XONSH_SOURCE	$XONSH_STORE_STDIN
$XONSH_STYLE_OVERRIDES	$XONSH_SUBPROC_CAPTURED_PRINT_STDERR	$XONSH_TRACEBACK_LOGFILE
$XONSH_TRACE_COMPLETIONS	$XONSH_TRACE_SUBPROC	$w*DIRS$
$w*PATH$

Windows OS¶
$ANSICON	$FORCE_POSIX_PATHS	$INTENSIFY_COLORS_ON_WIN

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

Interactive Prompt¶
$BOTTOM_TOOLBAR	$COLOR_INPUT	$COLOR_RESULTS
$DYNAMIC_CWD_ELISION_CHAR	$DYNAMIC_CWD_WIDTH	$IGNOREEOF
$INDENT	$LS_COLORS	$MULTILINE_PROMPT
$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_GITSTATUS_*
$XONSH_GITSTATUS_FIELDS_HIDDEN	$XONSH_HISTORY_MATCH_ANYWHERE	$XONSH_STDERR_POSTFIX
$XONSH_STDERR_PREFIX

Prompt Toolkit shell¶
$AUTO_SUGGEST	$AUTO_SUGGEST_IN_COMPLETIONS	$MOUSE_SUPPORT
$PROMPT_TOOLKIT_COLOR_DEPTH	$PTK_STYLE_OVERRIDES	$VI_MODE
$XONSH_AUTOPAIR	$XONSH_COPY_ON_DELETE

Asynchronous Prompt¶
$ASYNC_INVALIDATE_INTERVAL	$ASYNC_PROMPT_THREAD_WORKERS	$ENABLE_ASYNC_PROMPT

Interactive Prompt History¶
$HISTCONTROL	$XONSH_HISTORY_BACKEND	$XONSH_HISTORY_FILE
$XONSH_HISTORY_SAVE_CWD	$XONSH_HISTORY_SIZE	$XONSH_STORE_STDOUT

Tab-completion behavior.¶
$BASH_COMPLETIONS	$CASE_SENSITIVE_COMPLETIONS	$COMPLETIONS_BRACKETS
$COMPLETION_QUERY_LIMIT	$FUZZY_PATH_COMPLETION	$SUBSEQUENCE_PATH_COMPLETION

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

General¶

$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

$COMMANDS_CACHE_SAVE_INTERMEDIATE¶

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

configurable: True

default: False

store_as_str: False

$COMMANDS_CACHE_SIZE_WARNING¶

Number of files on the PATH above which a warning is shown.

configurable: True

default: 6000

store_as_str: False

$HOSTNAME¶

Automatically set to the name of the current host.

configurable: True

default: <function GeneralSetting.<lambda> at 0x7ff62e32aca0>

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 GeneralSetting.<lambda> at 0x7ff62e32ad30>

store_as_str: False

$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

$LOADED_RC_FILES¶

Whether or not any of the xonsh run control files were loaded at startup. This is a sequence of bools in Python that is converted to a CSV list in string form, ie [True, False] becomes 'True,False'.

configurable: False

default: ()

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: On Windows: it is Path value of register’s HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\Session Manager\Environment. On Mac OSX: ('/usr/local/bin', '/usr/bin', '/bin', '/usr/sbin', '/sbin') On Linux & on Cygwin & on MSYS, when detected that the distro is like arch, the default PATH is ('/usr/local/sbin', '/usr/local/bin', '/usr/bin', '/usr/bin/site_perl', '/usr/bin/vendor_perl', '/usr/bin/core_perl') and otherwise is ('~/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 (eg, .EXE) for filtering valid executables by. Each element must be uppercase.

configurable: True

default: []

store_as_str: False

$RAISE_SUBPROC_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.

configurable: True

default: False

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

$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 subrocess 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

$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

$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_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

$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: On Linux & Mac OSX: ['/etc/xonshrc', '~/.config/xonsh/rc.xsh', '~/.xonshrc']

On Windows: ['%ALLUSERSPROFILE%\\xonsh\\xonshrc', '~/.config/xonsh/rc.xsh', '~/.xonshrc']

store_as_str: False

$XONSHRC_DIR¶

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

configurable: True

default: On Linux & Mac OSX: ['/etc/xonsh/rc.d', '~/.config/xonsh/rc.d'] On Windows: ['%ALLUSERSPROFILE%\\xonsh\\rc.d', '~/.config/xonsh/rc.d']

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_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_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 ![]. 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_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 configuration information is stored.

configurable: False

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.

configurable: True

default: $XDG_DATA_HOME/xonsh

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

$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_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_INTERACTIVE¶

True if xonsh is running interactively, and False otherwise.

configurable: False

default: True

store_as_str: False

$XONSH_NO_AMALGAMATE¶

Setting this variable prior to starting xonsh to a truthy value will suppress amalgamated imports.

configurable: False

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_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_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 are all have the same effect.)

configurable: True

default: {}

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_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

$XONSH_TRACE_COMPLETIONS¶

Set to True to show completers invoked and their return values.

configurable: True

default: False

store_as_str: False

$XONSH_TRACE_SUBPROC¶

Set to True to show arguments list of every executed subprocess command.

configurable: True

default: False

store_as_str: False

$w*DIRS$¶

configurable: True

default: not defined

store_as_str: False

$w*PATH$¶

configurable: True

default: not defined

store_as_str: False

Windows OS¶

Windows OS specific settings

$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

`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

Interactive Prompt¶

$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

$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.PROMPT_FIELDS

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 that is backed by Python’s readline module

prompt_toolkit that 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.

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_GITSTATUS_*¶

Symbols for gitstatus prompt. Default values are:

XONSH_GITSTATUS_HASH_INDICATOR: :
XONSH_GITSTATUS_BRANCH: {CYAN}
XONSH_GITSTATUS_OPERATION: {CYAN}
XONSH_GITSTATUS_STAGED: {RED}●
XONSH_GITSTATUS_CONFLICTS: {RED}×
XONSH_GITSTATUS_CHANGED: {BLUE}+
XONSH_GITSTATUS_DELETED: {RED}-
XONSH_GITSTATUS_UNTRACKED: …
XONSH_GITSTATUS_STASHED: ⚑
XONSH_GITSTATUS_CLEAN: {BOLD_GREEN}✓
XONSH_GITSTATUS_AHEAD: ↑·
XONSH_GITSTATUS_BEHIND: ↓·
XONSH_GITSTATUS_LINES_ADDED: {BLUE}+
XONSH_GITSTATUS_LINES_REMOVED: {RED}-

configurable: True

default: None

store_as_str: False

$XONSH_GITSTATUS_FIELDS_HIDDEN¶

Fields to hide in {gitstatus} prompt (all fields below are shown by default.)

BRANCH
OPERATION
STAGED
CONFLICTS
CHANGED
DELETED
UNTRACKED
STASHED
CLEAN
AHEAD
BEHIND
LINES_ADDED
LINES_REMOVED

configurable: True

default: ()

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_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}”.

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}”.

configurable: True

default: ‘’

store_as_str: False

Prompt Toolkit shell¶

Only usable with $SHELL_TYPE=prompt_toolkit.

$AUTO_SUGGEST¶

Enable automatic command suggestions based on history, like in the fish shell.

Pressing the right arrow key inserts the currently displayed suggestion.

configurable: True

default: True

store_as_str: False

$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 .xonshrc file).Only available under the prompt-toolkit shell.

configurable: True

default: False

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 ASYC_PROPMT’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_FIELD 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. The option ignoredups will not save the command if it matches the previous command. The option ignoreerr will cause any commands that fail (i.e. return non-zero exit status) to not be added to the history list. The option erasedups will remove all previous commands that matches and updates the frequency. Note: erasedups is supported only in sqlite backend).

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_SAVE_CWD¶

Save current working directory to the history.

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¶

Whether or not to store the stdout and stderr streams in the history files.

configurable: True

default: False

store_as_str: False

Tab-completion behavior.¶

$BASH_COMPLETIONS¶

This is a list (or tuple) of strings that specifies where the bash_completion script may be found. The first valid path will be used. 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 individual completion scripts (like .../completes/ssh) do not need to be included here. The default values are platform dependent, but sane. To specify an alternate list, do so in the run control file.

configurable: True

default: Normally this is:

('/usr/share/bash-completion/bash_completion', )

But, on Mac it is:

('/usr/local/share/bash-completion/bash_completion', '/usr/local/etc/bash_completion')

Other OS-specific defaults may be added in the future.

store_as_str: False

$CASE_SENSITIVE_COMPLETIONS¶

Sets whether completions should be case sensitive or case insensitive.

configurable: True

default: True on Linux, False otherwise.

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¶

The number of completions to display before the user is asked for confirmation.

configurable: True

default: 100

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

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

$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

Environment Variables¶

General¶

$AUTO_CONTINUE¶

$COMMANDS_CACHE_SAVE_INTERMEDIATE¶

$COMMANDS_CACHE_SIZE_WARNING¶

$HOSTNAME¶

$HOSTTYPE¶

$LANG¶

$LC_COLLATE¶

$LC_CTYPE¶

$LC_MESSAGES¶

$LC_MONETARY¶

$LC_NUMERIC¶

$LC_TIME¶

$LOADED_RC_FILES¶

$OLDPWD¶

$PATH¶

$PATHEXT¶

$RAISE_SUBPROC_ERROR¶

$TERM¶

$THREAD_SUBPROCS¶

$UPDATE_OS_ENVIRON¶

$XDG_CONFIG_HOME¶

$XDG_DATA_HOME¶

$XONSHRC¶

$XONSHRC_DIR¶

$XONSH_APPEND_NEWLINE¶

$XONSH_CACHE_EVERYTHING¶

$XONSH_CACHE_SCRIPTS¶

$XONSH_CAPTURE_ALWAYS¶

$XONSH_COLOR_STYLE¶

$XONSH_CONFIG_DIR¶

$XONSH_DATA_DIR¶

$XONSH_DATETIME_FORMAT¶

$XONSH_DEBUG¶

$XONSH_ENCODING¶

$XONSH_ENCODING_ERRORS¶

$XONSH_INTERACTIVE¶

$XONSH_LOGIN¶

$XONSH_NO_AMALGAMATE¶

$XONSH_PROC_FREQUENCY¶

$XONSH_SHOW_TRACEBACK¶

$XONSH_SOURCE¶

$XONSH_STORE_STDIN¶

$XONSH_STYLE_OVERRIDES¶

$XONSH_SUBPROC_CAPTURED_PRINT_STDERR¶

$XONSH_TRACEBACK_LOGFILE¶

$XONSH_TRACE_COMPLETIONS¶

$XONSH_TRACE_SUBPROC¶

$w*DIRS$¶

$w*PATH$¶

Windows OS¶

$ANSICON¶

$FORCE_POSIX_PATHS¶

$INTENSIFY_COLORS_ON_WIN¶

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¶

Interactive Prompt¶

$BOTTOM_TOOLBAR¶

$COLOR_INPUT¶

$COLOR_RESULTS¶

$DYNAMIC_CWD_ELISION_CHAR¶

$DYNAMIC_CWD_WIDTH¶

$IGNOREEOF¶

$INDENT¶

$LS_COLORS¶

$MULTILINE_PROMPT¶

$PRETTY_PRINT_RESULTS¶

`cd` Behavior¶