Configuration

⚙️ Configuration

A config file answers three questions: which release, which families, and where to put them.

release: latest
destination: ~/.local/share/fonts/NerdFonts
refresh_font_cache: true
families:
  - JetBrainsMono
  - Hack
  - FiraCode

---

🔑 Keys

Key	Type	Required	Default	Meaning
release	string	—	latest	Which Nerd Fonts release to install from. latest or a tag such as v3.4.0.
destination	string	—	~/.local/share/fonts/NerdFonts	Root directory. Each family gets its own subdirectory inside it.
refresh_font_cache	bool	—	false	Run fc-cache -f <destination> after a successful install.
families	list of strings	✅	—	Nerd Font archive names, without the .zip suffix.

release

• latest resolves to the newest release at run time and uses the releases/latest/download/... URL form.
• A tag like v3.4.0 pins the exact release. Use this in dotfiles if you want identical bytes on every machine.
• An unknown tag is a user error: the tool exits 2 with nerd fonts release "vX.Y.Z" was not found.

destination

• ~ and ~/… expand to your home directory.
• Relative paths are kept relative to the working directory — handy for testing into ./tmp/fonts before touching your real font directory.
• The directory is created if it does not exist.

refresh_font_cache

• On Linux, set this to true. Fonts generally will not appear in applications until fc-cache has run.
• On macOS, fc-cache is usually not installed. The tool detects that, prints a note, and carries on — it is not an error.

families

Names must match the Nerd Fonts release archive names exactly — JetBrainsMono, not JetBrains Mono and not JetBrainsMono Nerd Font.

Never guess:

nerd-fonts-installer --font-names

That prints a ready-to-paste YAML block for whichever release your config pins.

Duplicates are rejected (duplicate font family "Hack"), and every name is validated against path traversal before it is used in a URL or a file path.

---

📄 Formats

The extension decides the parser.

Extension	Parser	Unknown keys
.yaml, .yml, .conf	YAML	❌ rejected
.json	JSON	❌ rejected

Decoding is strict on purpose: a typo like familes: fails loudly instead of silently installing nothing.

The same config in JSON

{
  "release": "latest",
  "destination": "~/.local/share/fonts/NerdFonts",
  "refresh_font_cache": true,
  "families": ["JetBrainsMono", "Hack", "FiraCode"]
}

---

📂 Where config files are found

When --config is not passed, resolution goes in this order and stops at the first hit:

1. --config <path> — explicit, wins over everything.
2. $NERD_FONTS_INSTALLER_CONFIG — an absolute or relative path.
3. Current directory:
   • ./nerd-fonts-installer.yaml
   • ./nerd-fonts-installer.yml
   • ./nerd-fonts-installer.json
   • ./nerd-fonts-installer.conf
   • ./nerd-fonts-installer/config.yaml
   • ./nerd-fonts-installer/config.yml
   • ./nerd-fonts-installer/config.json
   • ./nerd-fonts-installer/config.conf
4. $XDG_CONFIG_HOME — the same eight names, but only when XDG_CONFIG_HOME is set to an absolute path.
5. ~/.config — the same eight names, used when XDG_CONFIG_HOME is unset, empty, or relative.

The recommended home for a personal config:

~/.config/nerd-fonts-installer/config.yaml

When a config is discovered rather than passed explicitly, the tool prints which one it picked:

Using config /home/dev/.config/nerd-fonts-installer/config.yaml

Tip

A project-local ./nerd-fonts-installer.yaml overrides your personal config whenever you run the tool from that directory — useful for a repository that ships its own font set.

---

🌍 Environment variables

Variable	Effect
NERD_FONTS_INSTALLER_CONFIG	Path to a config file. Treated like --config, and honored by --font-names too.
XDG_CONFIG_HOME	Used for discovery when set to an absolute path.
HOME	Used to expand ~ in destination and to locate ~/.config.

NERD_FONTS_INSTALLER_CONFIG=/etc/fonts.yaml nerd-fonts-installer

---

🧪 Validating a config

--dry-run parses, validates, resolves the release, and prints the full plan without writing a byte:

nerd-fonts-installer --config fonts.yaml --dry-run

Anything wrong with the file surfaces here — before any download starts.

---

Next: 🚩 CLI Reference · 🍳 Recipes