Configuration reference

Every key recognised by starship.toml. Authoritative source: the structs in src/configs/ and the JSON Schema at .github/config-schema.json (regenerated from FullConfig).

Top-level (root) keys

Defined on StarshipRootConfig in src/configs/starship_root.rs:

Key	Type	Default	Purpose
format	String	"$all"	Main prompt format string
right_format	String	""	Right prompt format string
continuation_prompt	String	"[∙](bright-black) "	Continuation prompt format string
scan_timeout	u64	30	Directory scan timeout in milliseconds
command_timeout	u64	500	Per-command timeout in milliseconds
add_newline	bool	true	Print a leading blank line before the prompt
follow_symlinks	bool	true	Follow symlinks when scanning the cwd
palette	String?	none	Active palette name
palettes	Map<String, Palette>	{}	User-defined palettes
profiles	Map<String, String>	{}	User-defined profiles (alternate format strings)
internal_profiles	Map<String, String>	default_profiles()	Built-in profiles (do not modify; used by Claude Code statusline)

Per-module config

Every module has a config struct in src/configs/<name>.rs and corresponding implementation in src/modules/<name>.rs. The structs share these common fields:

Key	Type	Notes
format	String	The format string for the module
style	String	Default style for the module
disabled	bool	Skip this module entirely
symbol	String	Substituted for $symbol in the format

Toolchain modules (Rust, Python, Go, Node, Java, Ruby, Crystal, Dart, Deno, Elm, Erlang, Haskell, Helm, Java, Julia, Kotlin, Lua, Nim, Nix-shell, OCaml, Perl, PHP, Pulumi, Purescript, Python, Quarto, Raku, Red, Rlang, Ruby, Rust, Scala, Solidity, Swift, Terraform, Typst, Vagrant, Vlang, Zig) additionally accept:

Key	Type	Default	Purpose
detect_extensions	Vec<String>	per module	File extensions that trigger detection
detect_files	Vec<String>	per module	Filenames in cwd that trigger detection
detect_folders	Vec<String>	per module	Folder names in cwd that trigger detection
version_format	String	per module	How to render $version

Custom modules ([custom.<name>]) accept everything from CustomConfig in src/configs/custom.rs:

Key	Type	Default	Purpose
command	String | Vec<String>	""	Command to execute
when	bool | String	false	Condition for rendering
shell	Vec<String>	[]	Shell to run command/when (defaults to sh -c / cmd /C)
description	String	"<custom module>"	Used by starship explain
detect_files / detect_extensions / detect_folders	Vec<String>	[]	Detection rules
detect_env_vars	Vec<String>	[]	Env-var detection (!NAME for negation)
os	String?	none	OS family restriction
require_repo	bool	false	Run only inside a VCS repo
unsafe_no_escape	bool	false	Don't escape $output (allows DSL in command output)
ignore_timeout	bool	false	Skip command_timeout

Env-var modules ([env_var.<name>]) accept everything from EnvVarConfig in src/configs/env_var.rs:

Key	Type	Default	Purpose
variable	String?	the table key	Env var name to read (override the table key)
default	String?	none	Fallback if env var unset
format	String	"with [$env_value]($style) "	Format string
description	String	"<env_var module>"	Used by starship explain
style	String	"black bold dimmed"	Default style
disabled	bool	false
symbol	String	""

Where to look for the rest

Full module-by-module config is faithfully documented in docs/config/README.md. The structure of that file mirrors the module list. Anything in those structs that doesn't appear in the user docs is a bug — open an issue.

The JSON Schema at .github/config-schema.json is the machine-readable equivalent. Editors with a schema-aware TOML language server (Even Better TOML in VS Code, Helix, IntelliJ, …) get autocomplete and validation if your TOML starts with:

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

See also

• Configuration feature page — reading, layering, palettes, style strings.
• Configuration subsystem — how the schema turns into typed Rust.