Configuration

Starship is configured through a single starship.toml file. Every aspect of the prompt — what modules render, in what order, with what symbols, in what colors — comes from that file (or the per-module defaults if the file is empty or missing).

File location

Starship looks for the config in this order (see get_config_path_os in src/context.rs):

1. $STARSHIP_CONFIG — explicit path.
2. ~/.config/starship.toml — XDG default (or dirs::home_dir() equivalent on other platforms).

If neither exists, every module uses its <Name>Config::default() impl.

File anatomy

"$schema" = 'https://starship.rs/config-schema.json'

# Top-level (StarshipRootConfig) keys
add_newline = true
follow_symlinks = true
command_timeout = 500
scan_timeout = 30
format = "$all"
right_format = ""
continuation_prompt = "[∙](bright-black) "
palette = "ocean"

[palettes.ocean]
primary = "#0bc5ea"

# Per-module overrides
[character]
success_symbol = "[➜](bold green)"

[git_status]
disabled = false

# Custom modules
[custom.gitignore]
detect_files = [".gitignore"]
command = "wc -l < .gitignore"
format = "lines: [$output]($style) "
when = true

# Env-var modules (read environment variables)
[env_var.SHELL]
format = "[$env_value]($style) "

# Profiles (alternative format strings)
[profiles]
transient = "$character"

The "$schema" line at the top isn't required, but it activates JSON Schema validation in editors that support it (VS Code with Even Better TOML, Helix, IntelliJ, …) — the schema is generated from FullConfig via cargo run --features config-schema -- config-schema > .github/config-schema.json.

Configuration layers

For any given module, the effective configuration is computed as:

graph LR
    Default["<Name>Config::default()"] --> Merge["serde merge"]
    Toml["[name] table in starship.toml"] --> Merge
    Merge --> Effective["Effective config"]

<Name>Config::try_load(module.config) is called by every module's module(context) function. It runs Self::deserialize on the user's TOML subtable, with #[serde(default)] filling in any missing fields. If a field has an unknown key (typo), the serde deserializer logs a warning but continues with the rest.

Disabling a module

[package]
disabled = true

Context::is_module_disabled_in_config short-circuits before the module runs, so a disabled module pays zero cost.

Customizing the format

The default format is format = "$all", which expands to every entry in PROMPT_ORDER that the user hasn't disabled. Power users typically replace it with a hand-picked subset:

format = """
$username\
$hostname\
$directory\
$git_branch\
$git_status\
$cmd_duration\
$line_break\
$character"""

Trailing backslashes inside """ strings strip the newline after them, letting you keep the format readable while emitting it on one line.

Style strings

Color and attribute strings live inside [text](style) groups. They are space-separated tokens parsed by parse_style_string in src/config.rs:

Token	Example
Named color	red, green, bright-black, purple
Hex color	#abc, #abcdef
256-color	255
Palette reference	palette.primary (or just primary when active)
Background	bg:red, bg:#abc, bg:palette.foo
Attribute	bold, italic, underline, dimmed, inverted
Previous-segment color	prev_fg, prev_bg (used by powerline-style transitions)
Reset	none

Multiple tokens combine: bold underline #abcdef bg:red.

Palettes

Define color names once and reuse them everywhere:

palette = "catppuccin_mocha"

[palettes.catppuccin_mocha]
rosewater = "#f5e0dc"
flamingo = "#f2cdcd"
mauve = "#cba6f7"
red = "#f38ba8"
# ...

Style::resolve_palette in src/config.rs does the lookup. The palette name in palette = "..." selects which palette is active.

Detection knobs

Every project-detecting module (toolchain modules, custom modules, etc.) accepts:

• detect_files = ["pyproject.toml", "requirements.txt"] — exact filenames in the cwd.
• detect_extensions = ["py", "ipynb"] — file extensions.
• detect_folders = [".venv", "venv", "__pypackages__"] — directory names.
• detect_env_vars = ["VIRTUAL_ENV", "!IGNORE_ME"] — env vars (! prefix means negation).

These layer additively: any match counts.

Editing via the CLI

If you don't want to edit the file by hand:

# Set a specific key (uses toml_edit, preserves comments)
starship config character.success_symbol "[➜](bold green)"

# Toggle disabled
starship toggle git_status

# See the merged effective config
starship print-config

# See every default
starship print-config --default

These all live in src/configure.rs; see Configure subcommands.

Common configuration recipes

Goal	Knob
Two-line prompt with continuation	format ends with $line_break$character; continuation_prompt = "..."
Right prompt	Set right_format = "$cmd_duration"
Faster prompts on big repos	[git_status] disabled = true and/or [git_metrics] disabled = true
Hide language icons	Use the nerd-font-symbols preset or set [<lang>] symbol = ""
Stop printing a leading blank line	add_newline = false
Time-bound modules more aggressively	command_timeout = 200 (default 500)
Limit rayon pool	STARSHIP_NUM_THREADS=4 starship prompt

Related pages

• Format string DSL — the syntax inside format/right_format/profiles.
• Custom modules — [custom.<name>] tables.
• Profiles — alternative format strings.
• Presets — packaged starting points.
• Configuration subsystem — how the TOML becomes typed structs.