Environment Variables¶
The following displays information about the environment variables that effect xonsh performance in some way. It also lists their default values, if applicable.
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 files may be found. 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:
- (‘/etc/bash_completion’,
- ‘/usr/share/bash-completion/completions/git’)
But, on Mac it is:
- (‘/usr/local/etc/bash_completion’,
- ‘/opt/local/etc/profile.d/bash_completion.sh’)
And on Arch Linux it is:
- (‘/usr/share/bash-completion/bash_completion’,
- ‘/usr/share/bash-completion/completions/git’)
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
$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_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
$DIRSTACK_SIZE¶
Maximum size of the directory stack.
configurable: True
default: 20
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
$FORMATTER_DICT¶
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.environ.FORMATTER_DICT
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
$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: <xonsh.lazyasd.LazyObject object at 0x7fd6d91fe160>
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
$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 (https://github.com/jonathanslenders/python-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
$TEEPTY_PIPE_DELAY¶
The number of [seconds] to delay a spawned process if it has information being piped in via stdin. This value must be a float. If a value less than or equal to zero is passed in, no delay is used. This can be used to fix situations where a spawned process, such as piping into ‘grep’, exits too quickly for the piping operation itself. TeePTY (and thus this variable) are currently only used when $XONSH_STORE_STDOUT is True.
configurable: <xonsh.lazyasd.LazyBool object at 0x7fd6d8fc7d68>
default: 0.01
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_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
$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
$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 tuple 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%xonshxonshrc’, ‘~/.xonshrc’)
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, with higher values cooresponding to higher debuging levels and more information presented. Setting this variable prior to stating xonsh will supress amalgamated imports.
configurable: False
default: False
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_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_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_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