Recipes

🍳 Recipes

Copy-paste starting points for real setups.

---

🏠 Dotfiles

Keep the config in your dotfiles repository and symlink it:

ln -sf ~/dotfiles/nerd-fonts-installer.yaml \
       ~/.config/nerd-fonts-installer/config.yaml

Pin the release so every machine ends up byte-identical:

release: v3.4.0
destination: ~/.local/share/fonts/NerdFonts
refresh_font_cache: true
families:
  - JetBrainsMono
  - Hack
  - FiraCode
  - Meslo
  - SymbolsOnly

SymbolsOnly is worth including: it patches glyphs into fonts you have not replaced, which is what makes Starship and friends render everywhere.

---

🥾 Bootstrap script

#!/usr/bin/env bash
set -euo pipefail

mkdir -p ~/.config/nerd-fonts-installer

cat > ~/.config/nerd-fonts-installer/config.yaml <<'YAML'
release: latest
destination: ~/.local/share/fonts/NerdFonts
refresh_font_cache: true
families:
  - JetBrainsMono
  - Hack
  - FiraCode
YAML

nerd-fonts-installer --dry-run
nerd-fonts-installer

Safe under set -e: a cancelled run exits 0, and only real failures exit non-zero. See the exit-code table in 🚩 CLI Reference.

---

📦 Install the tool and the fonts in one script

#!/usr/bin/env bash
set -euo pipefail

if ! command -v nerd-fonts-installer >/dev/null; then
  base=https://github.com/worxbend/nerd-fonts-installer/releases/download/latest
  file=nerd-fonts-installer_latest_linux_amd64.tar.gz

  tmp="$(mktemp -d)"
  trap 'rm -rf "$tmp"' EXIT

  curl -fsSL -o "$tmp/$file" "$base/$file"
  curl -fsSL -o "$tmp/checksums.txt" "$base/checksums.txt"
  (cd "$tmp" && sha256sum --check --ignore-missing checksums.txt)

  tar -xzf "$tmp/$file" -C "$tmp"
  mkdir -p ~/.local/bin
  install -m 0755 "$tmp/${file%.tar.gz}/nerd-fonts-installer" ~/.local/bin/
fi

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

---

🐳 Docker / dev containers

Fonts inside a container only matter when the container renders text — a containerised editor, a VNC desktop, or an image you build for a workstation.

FROM debian:stable-slim

RUN apt-get update \
 && apt-get install -y --no-install-recommends ca-certificates curl fontconfig \
 && rm -rf /var/lib/apt/lists/*

ARG NFI=nerd-fonts-installer_latest_linux_amd64.tar.gz
RUN curl -fsSL -O "https://github.com/worxbend/nerd-fonts-installer/releases/download/latest/${NFI}" \
 && tar -xzf "${NFI}" \
 && install -m 0755 "${NFI%.tar.gz}/nerd-fonts-installer" /usr/local/bin/ \
 && rm -rf "${NFI}" "${NFI%.tar.gz}"

COPY fonts.yaml /etc/nerd-fonts-installer.yaml
ENV NERD_FONTS_INSTALLER_CONFIG=/etc/nerd-fonts-installer.yaml
RUN nerd-fonts-installer

Two things matter here:

• ca-certificates — the tool talks HTTPS to GitHub.
• fontconfig — only if you set refresh_font_cache: true. Without it the refresh is skipped with a note rather than failing.

Pin release: in fonts.yaml so your image builds stay reproducible.

---

🤖 Ansible

- name: Install Nerd Fonts
  hosts: workstations
  tasks:
    - name: Ensure config directory exists
      ansible.builtin.file:
        path: "{{ ansible_env.HOME }}/.config/nerd-fonts-installer"
        state: directory
        mode: "0755"

    - name: Write font config
      ansible.builtin.copy:
        dest: "{{ ansible_env.HOME }}/.config/nerd-fonts-installer/config.yaml"
        mode: "0644"
        content: |
          release: v3.4.0
          destination: ~/.local/share/fonts/NerdFonts
          refresh_font_cache: true
          families:
            - JetBrainsMono
            - Hack

    - name: Install fonts
      ansible.builtin.command: nerd-fonts-installer
      register: fonts
      changed_when: "'Installed' in fonts.stderr"

Re-running is safe: each family is re-downloaded and atomically replaced.

---

🔄 CI: check your config stays valid

A cheap job that catches a typo'd family name or a release that disappeared:

name: Fonts

on:
  pull_request:
    paths: ["fonts.yaml"]
  schedule:
    - cron: "0 6 * * 1"

jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6
      - name: Install nerd-fonts-installer
        run: |
          base=https://github.com/worxbend/nerd-fonts-installer/releases/download/latest
          file=nerd-fonts-installer_latest_linux_amd64.tar.gz
          curl -fsSL -O "$base/$file"
          tar -xzf "$file"
          echo "${PWD}/${file%.tar.gz}" >> "$GITHUB_PATH"
      - name: Validate the font config
        run: nerd-fonts-installer --config fonts.yaml --dry-run

--dry-run resolves the release and validates every family without downloading anything, so the job stays fast.

---

🌐 Remote boxes over SSH

The picker works fine over SSH, but the remote terminal will not have patched glyphs yet:

nerd-fonts-installer --interactive --icons ascii

For unattended provisioning, skip the picker entirely:

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

---

🧪 Try before you commit

Install into a scratch directory and inspect the files first:

release: latest
destination: ./tmp/fonts
refresh_font_cache: false
families:
  - Hack

nerd-fonts-installer --config ./try.yaml
ls ./tmp/fonts/Hack

Nothing outside ./tmp/fonts is touched.

---

🎯 Just one font, no config file

printf 'families:\n  - JetBrainsMono\n' > /tmp/one.yaml
nerd-fonts-installer --config /tmp/one.yaml

release and destination fall back to their defaults, so one line is a complete config.

---

Next: 🩹 Troubleshooting · ❓ FAQ