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.

$ANSICON $AUTO_CD $AUTO_PUSHD
$AUTO_SUGGEST $BASH_COMPLETIONS $BOTTOM_TOOLBAR
$CASE_SENSITIVE_COMPLETIONS $CDPATH $COLOR_INPUT
$COLOR_RESULTS $COMPLETIONS_BRACKETS $COMPLETIONS_CONFIRM
$COMPLETIONS_DISPLAY $COMPLETIONS_MENU_ROWS $COMPLETION_QUERY_LIMIT
$DIRSTACK_SIZE $DYNAMIC_CWD_ELISION_CHAR $DYNAMIC_CWD_WIDTH
$EXPAND_ENV_VARS $FORCE_POSIX_PATHS $FOREIGN_ALIASES_OVERRIDE
$FUZZY_PATH_COMPLETION $GLOB_SORTED $HISTCONTROL
$IGNOREEOF $INDENT $INTENSIFY_COLORS_ON_WIN
$LANG $LOADED_CONFIG $LOADED_RC_FILES
$MOUSE_SUPPORT $MULTILINE_PROMPT $OLDPWD
$PATH $PATHEXT $PRETTY_PRINT_RESULTS
$PROMPT $PROMPT_FIELDS $PUSHD_MINUS
$PUSHD_SILENT $RAISE_SUBPROC_ERROR $RIGHT_PROMPT
$SHELL_TYPE $SUBSEQUENCE_PATH_COMPLETION $SUGGEST_COMMANDS
$SUGGEST_MAX_NUM $SUGGEST_THRESHOLD $SUPPRESS_BRANCH_TIMEOUT_MESSAGE
$TERM $TITLE $UPDATE_COMPLETIONS_ON_KEYPRESS
$UPDATE_OS_ENVIRON $UPDATE_PROMPT_ON_KEYPRESS $VC_BRANCH_TIMEOUT
$VC_HG_SHOW_BRANCH $VIRTUAL_ENV $VI_MODE
$WIN_UNICODE_CONSOLE $XDG_CONFIG_HOME $XDG_DATA_HOME
$XONSHCONFIG $XONSHRC $XONSH_AUTOPAIR
$XONSH_CACHE_EVERYTHING $XONSH_CACHE_SCRIPTS $XONSH_COLOR_STYLE
$XONSH_CONFIG_DIR $XONSH_DATA_DIR $XONSH_DATETIME_FORMAT
$XONSH_DEBUG $XONSH_ENCODING $XONSH_ENCODING_ERRORS
$XONSH_GITSTATUS_* $XONSH_HISTORY_BACKEND $XONSH_HISTORY_FILE
$XONSH_HISTORY_SIZE $XONSH_INTERACTIVE $XONSH_LOGIN
$XONSH_PROC_FREQUENCY $XONSH_SHOW_TRACEBACK $XONSH_SOURCE
$XONSH_STDERR_POSTFIX $XONSH_STDERR_PREFIX $XONSH_STORE_STDIN
$XONSH_STORE_STDOUT $XONSH_TRACEBACK_LOGFILE  

Listing

$ANSICON

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

configurable: False

default: ‘<default not set>’

store_as_str: False


$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


$AUTO_SUGGEST

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

Pressing the right arrow key inserts the currently displayed suggestion. Only usable with $SHELL_TYPE=prompt_toolkit.

configurable: True

default: True

store_as_str: False


$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


$BOTTOM_TOOLBAR

Template string for the bottom toolbar. This may be parameterized 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


$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


$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


$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


$COMPLETIONS_BRACKETS

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

configurable: True

default: True

store_as_str: False


$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: False

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.

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_QUERY_LIMIT

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

configurable: True

default: 100

store_as_str: False


$DIRSTACK_SIZE

Maximum size of the directory stack.

configurable: True

default: 20

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


$EXPAND_ENV_VARS

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

configurable: True

default: True

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


$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 static configuration file $XONSH_CONFIG_DIR/config.json in the ‘env’ section and not in .xonshrc as loading of foreign aliases happens before``.xonshrc`` is parsed

configurable: True

default: False

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


$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


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

configurable: True

default: set()

store_as_str: True


$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


$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


$LANG

Fallback locale setting for systems where it matters

configurable: True

default: ‘C.UTF-8’

store_as_str: False


$LOADED_CONFIG

Whether or not the xonsh config file was loaded

configurable: False

default: False

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


$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


$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


$OLDPWD

Used to represent a previous present working directory.

configurable: False

default: ‘<default not set>’

store_as_str: False


$PATH

List of strings representing where to look for executables.

configurable: True

default: (‘/home/scopatz/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 extention strings (eg, .EXE) for filtering valid executables by. Each element must be uppercase.

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


$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


$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


$RIGHT_PROMPT

Template string for right-aligned text at the prompt. This may be parameterized 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


$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


$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 supress branch timeout warning messages.

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 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: ‘<default not set>’

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


$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


$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_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: ‘<default not set>’

store_as_str: False


$VI_MODE

Flag to enable vi_mode in the prompt_toolkit shell.

configurable: True

default: False

store_as_str: False


$WIN_UNICODE_CONSOLE

Enables unicode support in windows terminals. Requires the external library win_unicode_console.

configurable: False

default: True

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


$XONSHCONFIG

The location of the static xonsh configuration file, if it exists. This is in JSON format.

configurable: False

default: $XONSH_CONFIG_DIR/config.json

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.

configurable: True

default: On Linux & Mac OSX: ['/etc/xonshrc', '~/.xonshrc']

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

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_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_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 placesi.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 this variable prior to stating xonsh to 1 or True will supress amalgamated imports. Setting it to 2 will get some basic information like input transformation, command replacement. With 3 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_GITSTATUS_*

Symbols for gitstatus prompt. Default values are:

  • XONSH_GITSTATUS_HASH: :
  • XONSH_GITSTATUS_BRANCH: {CYAN}
  • XONSH_GITSTATUS_OPERATION: {CYAN}
  • XONSH_GITSTATUS_STAGED: {RED}●
  • XONSH_GITSTATUS_CONFLICTS: {RED}×
  • XONSH_GITSTATUS_CHANGED: {BLUE}+
  • XONSH_GITSTATUS_UNTRACKED:
  • XONSH_GITSTATUS_STASHED:
  • XONSH_GITSTATUS_CLEAN: {BOLD_GREEN}✓
  • XONSH_GITSTATUS_AHEAD: ↑·
  • XONSH_GITSTATUS_BEHIND: ↓·

configurable: True

default: ‘<default not set>’

store_as_str: False


$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 (deprecated).

configurable: False

default: ~/.xonsh_history

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_INTERACTIVE

True if xonsh is running interactively, and False otherwise.

configurable: False

default: ‘<default not set>’

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_PROC_FREQUENCY

The process frquency 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: ‘<default not set>’

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}” & “{NO_COLOR}”.

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}” & “{NO_COLOR}”.

configurable: True

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_STORE_STDOUT

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

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