fish

This page contains changes which are not marked for translation.

Resources

fish - the friendly interactive shell - is a smart and user-friendly command line shell for OS X, Linux, and the rest of the family. fish includes features like syntax highlighting, autosuggest-as-you-type, and fancy tab completions that just work, with no configuration required.

Refer to the "terminal emulator" article for some general usage pointers.

Important
fish is not a POSIX-compatible shell. It could cause issues if improperly set as a user's login shell. Refer to the "Caveats" section for how to safely set fish as a user's default shell.

Warning
fish should not be set as the system shell by making it the target of the /bin/sh symlink; this could result in an inoperable system.

Installation

USE flags

USE flags for app-shells/fish Friendly Interactive SHell

`+doc`	Add extra documentation (API, Javadoc, etc). It is recommended to enable per package instead of globally
`debug`	Enable extra debug codepaths, like asserts and extra output. If you want to get meaningful backtraces see https://wiki.gentoo.org/wiki/Project:Quality_Assurance/Backtraces
`nls`	Add Native Language Support (using gettext - GNU locale utilities)
`split-usr`	Enable behavior to support maintaining /bin, /lib, /sbin and /usr/sbin separately from /usr/bin and /usr/lib
`test`	Enable dependencies and/or preparations necessary to run tests (usually controlled by FEATURES=test but can be toggled independently)

Data provided by the Gentoo Package Database · Last update: 2025-04-05 11:50 More information about USE flags

Emerge

Install app-shells/fish:

root #emerge --ask app-shells/fish

Caveats

In Gentoo, the login shell (the shell started after a user logs in, as defined in /etc/passwd) sources /etc/profile, which in turn sources /etc/profile.env. This is needed to set up a functioning Gentoo environment, so a working POSIX shell is essential (refer to "Login shell in Gentoo" for details).

fish can not read these files, as it is not POSIX-compatible. Thus it is strongly advised not to set fish as the login shell for any user.

There is no reliable way to avoid this (see bug #545830). However, there is a way to use fish by default, as explained in the next section.

Those who nevertheless want to set fish as a login shell in /etc/passwd can jump down to "setting the fish shell as the login shell", though this is highly discouraged and can result in difficult issues.

fish as a default shell with Bash as the login shell

The following allows the use of fish by default, upon login or on starting a terminal emulator. This solution uses ~/.bashrc as a wrapper to have fish inherit the environment from the login shell, which is left as Bash.

Add the following to the user's ~/.bashrc, making sure it's placed below the test for an interactive shell, e.g. at the end of the file:

FILE ~/.bashrc

[...]
# Use fish in place of bash
# keep this line at the bottom of ~/.bashrc
[ -x /bin/fish ] && SHELL=/bin/fish exec fish

When bash is started as an interactive shell, this will automatically launch fish for the user, once bash has fully initialized the correct system environment. It will also set the SHELL environment variable to /bin/fish in fish.

Log into a new virtual console to test. Keeping open the current terminal may permit troubleshooting in case of any issue with the new configuration.

Note
When set up this way, launching an interactive bash prompt will drop to fish because of the line added to ~/.bashrc. To launch bash, ignore ~/.bashrc (beware that any commands in ~/.bashrc will not be executed):

user $bash --rcfile /etc/profile

This solution was suggested by one of the fish developers, the Arch wiki and Gentoo devs [1].

fish as shell with bass to create and import environment

Note
After a long and thorough discussion on bug #545830 and associated bugs, it was decided to use the above instructions to set fish as the default shell on Gentoo. This solution is potentially less robust, though it may still work.

Once fish is installed, install bass, which will permit fish to source /etc/profile on startup. bass is a utility to execute commands in bash and relay the environment variable changes to fish. The bass site has instructions for different installation methods, such as with the fisher plugin manager or OMF. We will explain here how to install bass manually, as this is the most basic method, however a plugin manager is arguably preferable.

Move into or create a base directory for the bass repository, for example:

user $cd ~/.local/opt

Clone the bass repository (requires Git), and move into the repository directory:

user ~/.local/opt $git clone https://github.com/edc/bass; cd bass

Install bass:

user ~/.local/opt/bass $make install

With bass, one can now have fish inherit the system-wide environment variables on startup, from bash.

Add the following line to ~/.config/fish/config.fish, above any other commands that would need the environment to be set up (config.fish may need to be created):

FILE ~/.config/fish/config.fish

bass source /etc/profile

Finally, restart fish if it is already running.

This solution was suggested by one of the fish developers and the Arch wiki.

Setting the fish shell as the login shell

Warning
After setting fish as the login shell there probably will be entries missing in the PATH variable and some packages that rely on /etc/profile.d will be broken.

Those who really wish to make fish their login shell can still technically do so. This is not recommended and can result in a broken system:

user $chsh -s /bin/fish

Configuration

fish starts by executing commands in ~/.config/fish/config.fish. The file can be created if it does not exist.

Since version 2.0, it is possible to configure fish from a Web browser session by running:

user $fish_config

Completions

fish can generate completions from man pages. To generate completions run:

user $fish_update_completions

Environment variables

The Gentoo Handbook explains how to set environment variables globally, for all users, and for the default shell (Bash).

Fish shell sets environment variables in a different way:

FILE ~/.conf/fish/config.fishAppend the PATH variable for fish shell

set -gx PATH "$PATH:$HOME/.local/bin:"

Tips

Using fish with Nix

The ~/.bashrc method from the "fish as a default shell with bash as the login shell" section above prevents nix-shell from applying its environment variable configuration. Nix users can use the following variant to work around this problem by disabling fish execution within a nix-shell:

FILE ~/.bashrc

[...]
# Use fish in place of bash
# keep this line at the bottom of ~/.bashrc
[ -x /bin/fish ] && [ -z "$IN_NIX_SHELL" ] && SHELL=/bin/fish exec fish

With this configuration in place, running nix-shell will result in a Bash shell. To start a nix-shell with fish, use nix-shell --command fish, which will correctly apply the Nix environment before launching fish.

Troubleshooting

Garbled display

The output of a shell can, in some conditions, become corrupt. Refer to the "terminal emulator" article for instructions to help fix this.

External resources