How to install and configure Starship on Linux

One of the things that make Linux-based operating systems great is the high degree of customization they offer us. We can customize and adapt (almost) everything to our needs, from the options the kernel is compiled with, to the desktop environment. On any Linux distribution, the terminal emulator is an essential tool for power users and system administrators. Starship is a free and open source plugin written in rust we can use to customize our favorite shell prompt by using a variety of modules.In this tutorial we see how to install and configure Starship on Linux, and how to integrate it in the Bash and Zsh shells.

In this tutorial you will learn:

How to install and configure Starship
How to use Starship with Bash and Zsh
How to customize Starship

article-main — How to install and configure Starship on Linux

Software requirements and conventions used

Category	Requirements, Conventions or Software Version Used
System	Distribution-independent
Software	Starship
Other	Root permissions for system-wide installation
Conventions	# – requires given linux-commands to be executed with root privileges either directly as a root user or by use of `sudo` command $ – requires given linux-commands to be executed as a regular non-privileged user

Installation

There are many ways to install Starship on our Linux system. The first (and generally the recommended one) is by using the package manager of our favorite distribution to download the Starship version packaged in its official repositories, if available. To install Starship on Fedora, the distribution sponsored by Red Hat, we can use the following command:

$ sudo dnf install starship

Starship is also available in the Archlinux “Community” repository. We can install the software via the pacman package manager:

$ sudo pacman -S starship

Unfortunately Starship is not available in the official repositories of Debian or Ubuntu, so we can either install it as a snap package, or by downloading the official installer script. To install Starship as a snap package, assuming snapd is already installed, we can run the following command:

$ sudo snap install starship

As an alternative, we can use the cross-distribution installer script method. The first thing we need to do, is to download the installer. To accomplish this task without leaving the command line, we can run:

$ curl -O https://starship.rs/install.sh

The command above will donwload the install.sh file in the directory from which it is invoked. The next step is to make the file executable:

$ chmod +x install.sh

If the script is launched without any option, it will try to install the Starship binary system-wide, in the /usr/local/bin directory. We can, however, choose an alternative installation path by passing it as argument to the -b option. For example, if we want to install Starship only for our current user, without the need to use privilege escalation, we can run:

$ ./install.sh -b ~/.local/bin

In the example above, we used the ~/.local/bin directory because, on modern Linux distributions, it is usually included in the user PATH by default. Once we launch the script, we will be promoted to confirm the installation:

Configuration
> Bin directory: /home/egdoc/.local/bin
> Platform: unknown-linux-musl
> Arch: x86_64

> Tarball URL: https://github.com/starship/starship/releases/latest/download/starship-x86_64-unknown-linux-musl.tar.gz
? Install Starship latest to /home/egdoc/.local/bin? [y/N] y

Using Starship in Bash and Zsh

Starship can be used in a variety of shells. In this tutorial, however, we will just see how to integrate it in what are probably the most used on Linux: Bash and Zsh. To get started with the former, all we have to do is to append the following line to the ~/.bashrc file:

eval "$(starship init bash)"

To integrate Starship in Zsh, instead, we must append the following line to the ~/.zshrc file:

eval "$(starship init zsh)"

The plugin will be loaded once we open an new shell session. As an alternative, we can manually source the file we modified. If using the Bash shell, for example, we could run:

$ source ~/.bashrc

As soon as we do it, and Starship is loaded, our shell prompt will change:

starship_base_prompt — The shell prompt produced by Starship

Customizing Starship

Starship functionalities are organized in modules. The options related to the various modules and their default values are represented in the Starship JSON schema. When we need to change the default value for an option, we need to write it in the ~/.config/starship.toml configuration file, which must be created if doesn’t already exist.

Inside the configuration file, we can enter generic, prompt-wide, configurations and module-specific ones. The former includes, for example, options like format, which is used to establish the prompt format and what modules are included in it. Here modules are referenced via variables named after them (e.g. the $git_branch variable references the “git_branch” module. By default all modules are included in the prompt.

Here is an example of a custom prompt configuration:

format = """
[ LINUXCONFIG STARSHIP PROMPT ](bold green)
[ ------------------------------------------------ ](bold green)
$all """
add_newline=false

In the example above, the text contained in the square brackets (e.g [ LINUXCONFIG STARSHIPT PROMPT ]) is called a format string: it can contain text and variables and can also be nested. The text included between parenthesis (e.g (bold green)), instead, is called a style string and is used to define the style of a format string.

After specifying the prompt format, we used the add_newline option and set it to false in order to avoid Starship to insert new lines between prompts (the latter is the default behavior). The above configuration (I admit is not the prettiest), produces the following result:

starship-custom-prompt — Our custom shell prompt

Modules configurations

When we want to change an option for a specific module, we must include the module name between brackets, and specify the option(s) and the value(s) we want to use, underneath it. Let’s see an example. Starship have several modules which are used for git integration. The “git_branch” module , for example, is used to display the active branch of a git repository, once we enter the corrisponding directory:

starship_git_branch — The Starship “git_branch” module displays the name of the active branch in the prompt

In the screenshot above, you can see I entered my “dotfiles” repository: thanks to the aforementioned module the repository branch is displayed in the prompt. If I modify a file, it is immediately reflected in the output. This is due to the “git_status” module, which is used to display information about a repository status:

starship_git_status — The “git_status” module highlights the presence of unstaged files

The [!] symbol, in red, is displayed after the name of the branch. This means there are modifications not yet staged. Once I add the changed files to the repository index, with the git add command, the prompt changes once again, this time the [+] symbol appears. This is to highlight the presence of staged changes:

starship_git_status_staged — The [+] symbols means there are staged changes

The [+] symbol disappears once we commit the changes. The list of the options and symbols used by the “git_status” module are reported in the official Starship documentation page and in the JSON schema:

[...] 
"git_status": {
      "default": {
        "ahead": "⇡",
        "behind": "⇣",
        "conflicted": "=",
        "deleted": "✘",
        "disabled": false,
        "diverged": "⇕",
        "format": "([\\[$all_status$ahead_behind\\]]($style) )",
        "ignore_submodules": false,
        "modified": "!",
        "renamed": "»",
        "staged": "+",
        "stashed": "\\$",
        "style": "red bold",
        "untracked": "?",
        "up_to_date": ""
      },
      "allOf": [
        {
          "$ref": "#/definitions/GitStatusConfig"
        }
      ]
    },
[...]

Say we want to change the symbol displayed when there are modified files in the repository. What we have to do is to write the name of the module between brackets in the configuration file, and override the value used for the “modified” option (here, just as an example, we use the ➜ symbol):

[git_status]
modified = "➜"

We can use the same principle also to completely disable a specific module. To disable the “git_status” module, for example, we would write:

[git_status]
disabled = true

Conclusions

In this tutorial we learned how to install and perform a basic configuration of the Starship plugin on Linux. This plugin can be used to customized our favorite shell prompt in a variety of ways. Here we just started to see some of the functionalities like the integration with a git repository. For a complete list of Starship modules and their options, please take a look at the official documentation.