Modules

Active contributors: Matan Kushner, David Knaack, Thomas O'Donnell, Kevin Song, Dario Vladović

Purpose

A module is one self-contained piece of the prompt. Each module decides whether to render based on the current directory, environment, command status, or VCS state, then produces a styled string. Starship ships ~100 modules out of the box. They live in src/modules/<name>.rs, with paired config in src/configs/<name>.rs. The full registry is ALL_MODULES in src/module.rs; the default render order is PROMPT_ORDER in src/configs/starship_root.rs.

This section groups them by purpose. The actual rendering pipeline that calls these modules is described in Architecture, and the module shape itself is described in Patterns and conventions.

How modules connect to the rest of the system

graph LR
    Format["format string<br/>$rust$git_branch..."] --> Parser["StringFormatter<br/>(pest grammar)"]
    Parser --> Vars["Set of $variable names"]
    Vars --> Handle["modules::handle(name, ctx)<br/>(src/modules/mod.rs)"]
    Handle --> ModuleFn["module(ctx) in<br/>src/modules/<name>.rs"]
    ModuleFn -->|"Detect"| Scan["Context::try_begin_scan()<br/>or env-var checks"]
    ModuleFn -->|"Compute"| Exec["context.exec_cmd()<br/>or read_file()"]
    ModuleFn -->|"Render"| FmtAgain["StringFormatter::parse"]
    FmtAgain --> Segments["Vec<Segment>"]

Subgroups

Starship has too many modules to enumerate one per page. They are organized below by what they show and where their data comes from. Each sub-page covers the modules in detail.

Group	Page	Examples
Language and toolchain version modules	Language toolchain modules	rust, python, nodejs, golang, java, c, cpp, dotnet, …
Version control modules	VCS modules	git_branch, git_status, git_metrics, hg_*, fossil_*, pijul_channel, vcs, vcsh
Cloud and infrastructure modules	Cloud and infra modules	aws, azure, gcloud, kubernetes, openstack, terraform, pulumi, helm, docker_context
System and shell modules	System modules	directory, username, hostname, os, shell, time, battery, memory_usage, jobs, cmd_duration, status, character
Claude Code statusline modules	Claude Code modules	claude_model, claude_context, claude_cost
Special-purpose modules	Special modules	custom, env_var, fill, line_break, package

Module lifecycle

The lifecycle of a single module on a single prompt looks like this:

1. print::get_prompt parses format (or right_format / a profile) and asks StringFormatter for the set of $variables it references.
2. For every variable that names a module in ALL_MODULES, handle_module calls modules::handle(name, context).
3. modules::handle dispatches to crate::modules::<name>::module(context). If the user has set [<name>] disabled = true, the dispatcher short-circuits in print::handle_module.
4. The module function returns Option<Module<'a>>. Returning None means "I do not apply" (no Rust project here, no AWS profile set, …) and the module simply does not render.
5. The returned segments are flattened into the parent root module, and nu_ansi_term::AnsiStrings collapses redundant ANSI escapes.

The $all variable expands to "every module in PROMPT_ORDER not already named in the format and not disabled" — see all_modules_uniq in src/print.rs. This is what makes the default format = "$all" show every module.

Adding a new module

The Contributing guide has the canonical checklist. The TL;DR of what files you must touch:

• src/configs/<name>.rs — new <Name>Config struct.
• src/configs/mod.rs — pub mod <name>; and a field on FullConfig.
• src/configs/starship_root.rs — entry in PROMPT_ORDER (only if the module should render by default).
• src/module.rs — entry in ALL_MODULES (alphabetical; there is a unit test that enforces sort order).
• src/modules/<name>.rs — the actual module(context) function.
• src/modules/mod.rs — mod <name>;, a match arm in handle(), and a description in description().
• .github/config-schema.json — regenerate via cargo run --features config-schema -- config-schema > .github/config-schema.json.
• docs/config/README.md — user-facing documentation (with the standard "Default values" / "Variables" tables).
• docs/public/presets/toml/*.toml — appropriate preset entries.

Then write tests in your new module file using ModuleRenderer (see Testing).