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

# Built-in Aliases

This page describes the xonsh built-in commands and aliases.

## `cd`

Changes the directory. If no directory is specified (i.e. if there are no arguments) then this changes to the current user’s home directory.

## `pushd`

Adds a directory to the top of the directory stack, or rotates the stack, making the new top of the stack the current working directory.

    usage: pushd [-h] [-n] [-q] [+N|-N|dir]

    Adds a directory to the top of the directory stack, or rotates the stack,
    making the new top of the stack the current working directory.

    On Windows, if the path is a UNC path (begins with `\\<server>\<share>`) and if the `DisableUNCCheck` registry
    value is not enabled, creates a temporary mapped drive letter and sets the working directory there, emulating
    behavior of `PUSHD` in `CMD.EXE`

    positional arguments:
      +N|-N|dir    * dir :
                       Makes dir be the top of the stack,
                       making it the new current directory as if it had been supplied as an argument to the cd builtin.
                   * +N :
                       Brings the Nth directory (counting from the left of the list printed by dirs, starting with zero)
                       to the top of the list by rotating the stack.
                   * -N :
                       Brings the Nth directory (counting from the right of the list printed by dirs, starting with zero)
                       to the top of the list by rotating the stack.

    options:
      -h, --help   show this help message and exit
      -n, --cd     Suppresses the normal change of directory when adding directories to the stack,
                   so that only the stack is manipulated.
      -q, --quiet  Do not call dirs, regardless of $PUSHD_SILENT

## `popd`

Removes entries from the directory stack.

    usage: popd [-h] [-n] [-q] [+N|-N]

    When no arguments are given, popd removes the top directory from the stack
    and performs a cd to the new top directory.
    The elements are numbered from 0 starting at the first directory listed with ``dirs``;
    that is, popd is equivalent to popd +0.

    positional arguments:
      +N|-N        Removes the Nth directory (counting from the left/right of the list printed by dirs w.r.t. -/+ prefix),
                   starting with zero.

    options:
      -h, --help   show this help message and exit
      -n, --cd     Suppresses the normal change of directory when removing directories from the stack,
                   so that only the stack is manipulated.
      -q, --quiet  Do not call dirs, regardless of $PUSHD_SILENT

## `dirs`

Displays the list of currently remembered directories. Can also be used to clear the directory stack.

    usage: dirs [-h] [-c] [-p] [-v] [-l] [N]

    Manage the list of currently remembered directories.

    positional arguments:
      N           Displays the Nth directory (counting from the left/right according to +/x prefix respectively),
                  starting with zero

    options:
      -h, --help  show this help message and exit
      -c          Clears the directory stack by deleting all of the entries.
      -p          Print the directory stack with one entry per line.
      -v          Print the directory stack with one entry per line,
                  prefixing each entry with its index in the stack.
      -l          Produces a longer listing; the default listing format
                  uses a tilde to denote the home directory.

## `jobs`

Display a list of all current jobs.

## `fg`

Bring the currently active job to the foreground, or, if a single number is given as an argument, bring that job to the foreground.

## `bg`

Resume execution of the currently active job in the background, or, if a single number is given as an argument, resume that job in the background.

## `disown`

The behavior of this command matches the behavior of zsh’s disown command which is as follows:

Remove the specified jobs from the job table; the shell will no longer report their status, and will not complain if you try to exit an interactive shell with them running or stopped. If no job is specified, disown the current job. If the jobs are currently stopped and the $AUTO_CONTINUE option is set ($AUTO_CONTINUE = True), a warning is printed containing information about how to make them running after they have been disowned. If one of the latter two forms is used, the jobs will automatically be made running, independent of the setting of the $AUTO_CONTINUE option.

## `EOF`, `exit`, and `quit`

The commands `EOF`, `exit`, and `quit` all alias the same action, which is to leave xonsh in a safe manner. Typing `Ctrl-d` is the same as typing `EOF` and pressing enter.

## `exec` and `xexec`

    usage: xexec [-h] [-l] [-c] [-a NAME] ...

    exec (also aliased as xexec) uses the os.execvpe() function to
    replace the xonsh process with the specified program.

    This provides the functionality of the bash 'exec' builtin::

        >>> exec bash -l -i
        bash $

    positional arguments:
      command          program to launch along its arguments

    options:
      -h, --help       show this help message and exit
      -l, --login      the shell places a dash at the
                       beginning of the zeroth argument passed to command to simulate login
                       shell.
      -c, --clean      causes command to be executed with an empty environment.
      -a, --name NAME  the shell passes name as the zeroth argument
                       to the executed command.

    Notes
    -----
    This command **is not** the same as the Python builtin function
    exec(). That function is for running Python code. This command,
    which shares the same name as the sh-lang statement, is for launching
    a command directly in the same process. In the event of a name conflict,
    please use the xexec command directly or dive into subprocess mode
    explicitly with ![exec command]. For more details, please see
    http://xon.sh/faq.html#exec.

## `source`

Executes the contents of the provided files in the current context. This, of course, only works on xonsh and Python files (`*.xsh`, `*.py`). Use `-e` to ignore extension.

## `source-bash`

Like the `source` command but for Bash files. This is a thin wrapper around the `source-foreign` alias where the `shell` argument is automatically set to `bash`.

## `source-zsh`

Like the `source` command but for ZSH files. This is a thin wrapper around the `source-foreign` alias where the `shell` argument is automatically set to `zsh`.

## `source-foreign`

Like the `source` command but for files in foreign (non-xonsh) languages. It will pick up the environment and any aliases.

    usage: source-foreign [-h] [-i] [-l] [--envcmd ENVCMD] [--aliascmd ALIASCMD]
                          [--extra-args EXTRA_ARGS] [-u] [-p PREVCMD]
                          [--postcmd POSTCMD] [--funcscmd FUNCSCMD]
                          [--sourcer SOURCER] [--use-tmpfile]
                          [--seterrprevcmd SETERRPREVCMD]
                          [--seterrpostcmd SETERRPOSTCMD] [--overwrite-aliases]
                          [--suppress-skip-message] [--show] [-d] [-n]
                          shell files_or_code [files_or_code ...]

    Sources a file written in a foreign shell language.

    positional arguments:
      shell                 Name or path to the foreign shell
      files_or_code         file paths to source or code in the target language.

    options:
      -h, --help            show this help message and exit
      -i, --interactive     whether the sourced shell should be interactive
      -l, --login           whether the sourced shell should be login
      --envcmd ENVCMD       command to print environment
      --aliascmd ALIASCMD   command to print aliases
      --extra-args EXTRA_ARGS
                            extra arguments needed to run the shell
      -u, --unsafe          whether the source shell should be run safely, and not raise any errors, even if they occur.
      -p, --prevcmd PREVCMD
                            command(s) to run before any other commands, replaces traditional source.
      --postcmd POSTCMD     command(s) to run after all other commands
      --funcscmd FUNCSCMD   code to find locations of all native functions in the shell language.
      --sourcer SOURCER     the source command in the target shell language.
                            If this is not set, a default value will attempt to be
                            looked up based on the shell name.
      --use-tmpfile         whether the commands for source shell should be written to a temporary file.
      --seterrprevcmd SETERRPREVCMD
                            command(s) to set exit-on-error before any other commands.
      --seterrpostcmd SETERRPOSTCMD
                            command(s) to set exit-on-error after all other commands.
      --overwrite-aliases   flag for whether or not sourced aliases should replace the current xonsh aliases.
      --suppress-skip-message
                            flag for whether or not skip messages should be suppressed.
      --show                show the script output.
      -d, --dry-run         Will not actually source the file.
      -n, --non-interactive
                            Deprecated: The default mode runs in non-interactive mode.

## `history`

Tools for dealing with xonsh history. See the history tutorial for more information all the history command and all of its sub-commands.

    usage: history [-h]
                   {show,id,file,info,pull,flush,off,on,clear,delete,gc,transfer,diff} ...

    Try 'history <command> --help' for more info

    options:
      -h, --help            show this help message and exit

    commands:
      {show,id,file,info,pull,flush,off,on,clear,delete,gc,transfer,diff}
        show                Display history of a session, default command
        id                  Display the current session id
        file                Display the current history filename
        info                Display information about the current history
        pull                Pull history from other parallel sessions.
        flush               Flush the current history to disk
        off                 History will not be saved for this session
        on                  History will be saved for the rest of the session (default)
        clear               One-time wipe of session history
        delete              Delete all commands matching a pattern
        gc                  Launches a new history garbage collector
        transfer            Transfer entries between history backends.
        diff                Diff two xonsh history files

## `timeit`

Runs timing study on arguments. Similar to IPython’s `%timeit` magic.

## `showcmd`

Displays how commands and arguments are evaluated. Use `-e` to expand aliases.

    @ showcmd echo The @('args') @(['list', 'is']) $(echo here) "and" --say="hello" to @([]) you
    ['echo', 'The', 'args', 'list', 'is', 'here', 'and', '--say="hello"', 'to', 'you']
    @ showcmd ls
    ls
    @ showcmd -e ls
    ['ls', '--group-directories-first', '-A', '--color']

## `trace`

Provides an interface to printing lines of source code prior to their execution.

    usage: trace [-h] {on,start,add,off,stop,del,rm,color,ls} ...

    Tool for tracing xonsh code as it runs.

    options:
      -h, --help            show this help message and exit

    commands:
      {on,start,add,off,stop,del,rm,color,ls}
        on (start, add)     begins tracing selected files.
        off (stop, del, rm)
                            removes selected files fom tracing.
        color (ls)          output color management for tracer

## `xonfig`

Manages xonsh configuration information.

    usage: xonfig [-h] {info,web,wizard,styles,colors,tutorial} ...

    Manage xonsh configuration.

    options:
      -h, --help            show this help message and exit

    commands:
      {info,web,wizard,styles,colors,tutorial}
        info                Displays configuration information
        web                 Launch configurator in browser.
        wizard              Launch configurator in terminal
        styles              Prints available xonsh color styles
        colors              Preview color style
        tutorial            Launch tutorial in browser.

## `xcontext`

    @ xcontext
    [Current xonsh session]
    xpython: /home/snail/.local/xonsh-env/bin/python # Python 3.12.10
    xpip: /home/snail/.local/xonsh-env/bin/python -m pip

    [Current commands environment]
    xonsh: /home/snail/.local/xonsh-env/bin/xonsh
    python: /usr/bin/python # Python 3.11.6
    pip: /usr/bin/pip

    CONDA_DEFAULT_ENV: my-env

Report information about the current xonsh environment, including paths to the Python interpreter, pip, xonsh itself, and relevant environment variables.

## `xontrib`

Manages xonsh extensions. More information is available at Tutorial: Extensions (Xontribs)

## `xpip`

Runs the `pip` package manager for xonsh itself. Useful for installations where xonsh is in an isolated environment (e.g. conda, mamba, homebrew).

    @ which pip
    /usr/bin/pip  # system pip
    @ which xpip
    /home/snail/.local/xonsh-env/bin/python -m pip  # current xonsh session pip
    @ xpip install fire
    @ import fire
    @ fire
    <module 'fire' from '/home/snail/.local/xonsh-env/lib/python3.11/site-packages/fire/__init__.py'>

## `xpython`

Alias to the Python interpreter that is currently running xonsh (`sys.executable`). This is useful for running Python modules or scripts in the same environment as the shell itself, especially in complex setups like AppImage.

    @ python -V
    Python 3.12.10
    @ xpython -V
    Python 3.11.9
    @ which python
    /opt/homebrew/bin/python
    @ which xpython
    /home/snail/.local/xonsh-env/bin/python

## `xreset`

Clean the xonsh context. All user variables will be deleted.

## `@thread` and `@unthread`

Use `@thread` and `@unthread` to run command as threadable or unthreadable e.g to have a result of ssh command:

    @ !(@thread ssh host -T "echo 1")

## Windows cmd Aliases

The following aliases on Windows are expanded to `['cmd', '/c', alias]`:

    {'cls': ['cmd', '/c', 'cls'],
     'copy': ['cmd', '/c', 'copy'],
     'del': ['cmd', '/c', 'del'],
     'dir': ['cmd', '/c', 'dir'],
     'erase': ['cmd', '/c', 'erase'],
     'md': ['cmd', '/c', 'md'],
     'mkdir': ['cmd', '/c', 'mkdir'],
     'mklink': ['cmd', '/c', 'mklink'],
     'move': ['cmd', '/c', 'move'],
     'rd': ['cmd', '/c', 'rd'],
     'ren': ['cmd', '/c', 'ren'],
     'rename': ['cmd', '/c', 'rename'],
     'rmdir': ['cmd', '/c', 'rmdir'],
     'time': ['cmd', '/c', 'time'],
     'type': ['cmd', '/c', 'type'],
     'vol': ['cmd', '/c', 'vol'],
     }

## `activate`/`deactivate` on Windows with Anaconda

On Windows with an Anaconda Python distribution, `activate` and `deactivate` are aliased to `['source-bat activate']` and `['source-bat deactivate']`. This makes it possible to use the same commands to activate/deactivate conda environments as in cmd.exe.

## `sudo` on Windows

On Windows, if no executables named `sudo` are found, Xonsh adds a `sudo` alias that poly fills the “run as Admin” behavior with the help of `ShellExecuteEx` and `ctypes`. It doesn’t support any actual `sudo` parameters and just takes the command to run.

## `ls`

The `ls` command is aliased to `['ls', '--color=auto', '-v']` normally. On Mac OSX it is instead aliased to `['ls', '-G']`.

## `grep`

The `grep` command is aliased to `['grep', '--color=auto']`.