Custom modules

A user-defined module under [custom.<name>] lets you display arbitrary information without writing Rust. Implementation: src/modules/custom.rs; config: src/configs/custom.rs.

Minimal example

[custom.docker]
detect_files = ["docker-compose.yml", "Dockerfile"]
command = "docker --version | cut -d' ' -f3"
format = "[$symbol$output]($style) "
symbol = "🐳 "
style = "blue"

When you cd into a directory containing docker-compose.yml, the prompt picks up 🐳 27.2.0 (or whatever your Docker version is).

All knobs

Field	Default	Purpose
format	[$symbol($output )]($style)	Format string. Special variable $output is replaced with command's stdout.
command	""	Shell command to run (or list of strings). Output is captured; trailing whitespace stripped.
when	false	true to always run; false to skip; or a string command — module renders only if exit status is 0.
shell	[]	The shell + args used to run command and when. Defaults to sh -c on Unix and cmd /C on Windows.
description	"<custom module>"	Description shown by starship explain.
detect_files	[]	Filenames in cwd to trigger detection.
detect_extensions	[]	File extensions to trigger detection.
detect_folders	[]	Folder names in cwd to trigger detection.
symbol	""	Substituted for $symbol.
style	"green bold"	Substituted for $style.
disabled	false	Standard.
os	None	Restrict to OS family (linux, macos, windows, unix).
require_repo	false	Only run inside a VCS repo (anything Context::get_repo() returns Ok for).
unsafe_no_escape	false	When true, $output is not escaped, so it can contain Starship DSL syntax (text groups, conditionals, etc.). Use with care.
ignore_timeout	false	Skip command_timeout. Use sparingly — slow custom modules slow every prompt.

The detection layers are additive: any matching detect_files/detect_extensions/detect_folders counts. If none of those match, when decides.

Detection rules

A custom module renders if all of these are true:

1. disabled is not true.
2. os (if set) matches the current OS family.
3. require_repo (if set) and Context::get_repo().is_ok() is true.
4. At least one of:
   • detect_files/detect_extensions/detect_folders matches the cwd, OR
   • when is true, OR
   • when is a command whose exit status is 0.

If when is a command, it is run with the same shell config as command, with command_timeout enforced. Its output is discarded.

Shell selection

shell = ["powershell", "-NoProfile", "-Command"]

Each element after the first is passed to the shell. The command itself is appended as the last argument. If shell is empty:

• Unix: sh -c <command>.
• Windows: cmd /C <command>.

If you need to run a binary directly without going through a shell, set shell = ["bash", "-c"] (for example) anyway — Starship always wraps command in a shell-quote-friendly form.

Variable mapping

Variables available inside format:

Variable	Source
$output	command stdout, trimmed
$symbol	symbol config
$style	style config

The user's format is parsed by StringFormatter, with unsafe_no_escape choosing between map (escapes DSL chars) and map_no_escaping (does not).

Multiple custom modules

[custom.foo] # ...
[custom.bar] # ...

Both are dispatched when format contains $custom. To pin order, use ${custom.foo} and ${custom.bar} explicitly:

format = "${custom.bar}${custom.foo}$character"

print::handle_module walks the [custom] table, dispatching each entry via modules::handle("custom.<name>", context). Modules already named explicitly in the format are skipped to avoid double-rendering.

Performance considerations

• A command that runs a process pays at minimum the OS process-spawn cost — typically 1-10ms on Unix, more on Windows. Adding even a few custom modules with shell commands can add up.
• command_timeout (default 500ms) caps each invocation. The next iteration of process_control is what kills runaway processes.
• If your module is run on every prompt redraw, prefer reading a file (use read_file directly via a thin Rust wrapper or write a real Rust module) over running a process.

Where to read more

• The full user-facing reference is in docs/config/README.md under "Custom commands".
• Implementation: src/modules/custom.rs.
• See also Special modules.