Configuring the terminal to run Elvish

This is the recommended way to use Elvish as your default shell.

macOS terminals

Terminal	Instructions
Terminal.app	Open `Terminal > Preferences`. Ensure you are on the `Profiles` tab (which should be the default tab). In the right-hand panel, select the `Shell` tab. Tick `Run command`, put the path to Elvish in the textbox next to it, and untick `Run inside shell`.
iTerm2	Open `iTerm > Preferences`. Select the `Profiles` tab. In the right-hand panel, change the dropdown under Command from `Login Shell` to either `Custom Shell` or `Command`, and put the path to Elvish in the textbox next to it.

Linux and BSD terminals

Terminal	Instructions
GNOME Terminal	Open `Edit > Preferences`. In the right-hand panel, select the `Command` tab. Tick `Run a custom command instead of my shell`, and set `Custom command` to the path to Elvish.
Konsole	Open `Settings > Edit Current Profile`. Set `Command` to the path to Elvish.
XFCE Terminal	Open `Edit > Preferences`. Tick `Run a custom command instead of my shell`, and set `Custom command` to the path to Elvish.

The following terminals only support a command-line flag to change the shell. Depending on your DE, you can either create a wrapper script or modify the desktop file:

Terminal	Instructions
LXTerminal	Pass `--command $path_to_elvish`.
rxvt	Pass `-e $path_to_elvish`.
xterm	Pass `-e $path_to_elvish`.

tmux

Add the following to ~/.tmux.conf:

if-shell 'which elvish' 'set -g default-command elvish'

This only launches Elvish if it’s available, so it’s safe to have in a .tmux.conf that you sync with machines where you haven’t installed Elvish yet.

Windows terminals

Terminal	Instructions
Windows Terminal	Press `Ctrl`+`,` to open Settings. Select `Add a new profile` from the left sidebar, and click `New empty profile`. Set `Name` to “Elvish” and `Command line` to the path to Elvish. Select `Startup` from the left sidebar, and set `Default profile` to Elvish. Hit `Save`.
ConEmu	Press `Win`+`Alt`+`T` to open Startup Tasks. Click `±` below the list of existing tasks. Set the name to “Elvish”, enter the path to Elvish in the textbox below Commands, and tick `Default task for new console`. Click `Save settings`.

VS Code

Open the command palette and run “Open User Settings (JSON)”. Add the following:

    "terminal.integrated.defaultProfile.linux": "elvish",
    "terminal.integrated.profiles.linux": {
        "elvish": {
            "path": "elvish"
        },
    }

Change linux to osx or windows depending on your operating system. See VS Code’s documentation for more details.

On Unix systems, you can also use Elvish as your login shell. Run the following Elvish snippet:

use runtime
if (not (has-value [(cat /etc/shells)] $runtime:elvish-path)) {
    echo $runtime:elvish-path | sudo tee -a /etc/shells
}
chsh -s $runtime:elvish-path

You can change your login shell back to the system default with chsh -s ''.

Dealing with incompatible programs

Some programs invoke the user’s login shell assuming that it is a traditional POSIX-like shell, so they won’t work correctly if your login shell is Elvish. This section lists programs known to have issues and possible workarounds.

If you can’t work around the issue, it may be easier to switch the login shell back to the system default and configure your terminal to launch Elvish instead.

Vim / Neovim

Add the following to .vimrc or .nvimrc:

set shell=/bin/sh

GDB

Create an alias that sets the SHELL environment variable to /bin/sh:

fn gdb {|@a|
  env SHELL=/bin/sh gdb $@a
}

(Reported in #1795.)

vscode-neovim

No workaround has been tested yet. Launching VS Code with the SHELL environment variable set to /bin/sh may work.

If you use vscode-neovim and have found and tested a workaround, please send a pull request updating this document.

(Reported in #1804.)

Using Elvish as your default shell