This page explains how to report bugs effectively against the Nerd Fonts project, documents the icon request policy (including when individual icon additions are and are not accepted), and walks through the fields of the icon_request.yml GitHub issue template.
For common solutions to known issues such as font recognition, scaling problems, or installation failures, see Troubleshooting. For contributing new font families to the repository, see Adding New Fonts.
When filing a bug that is not an icon request, include the following information to allow maintainers to reproduce and diagnose the issue quickly.
| Category | Information to Include |
|---|---|
| Environment | OS, terminal emulator, shell, font renderer |
| Font | Exact patched font name and version (e.g., JetBrainsMono Nerd Font 2.304) |
| Patcher version | Output of font-patcher --version if the bug is in the patcher |
| Reproduction steps | Minimal set of steps that reliably reproduce the issue |
| Expected vs. actual | What you expected to see and what you actually observed |
| Error output | Full terminal output, including any fontforge or Python tracebacks |
The readme.md links to several community resources for common issues:
Nerd Fonts is an icon set aggregator: it incorporates entire upstream icon fonts (Font Awesome, Devicons, Octicons, Material Design Icons, etc.) rather than hand-picking individual glyphs. This shapes the policy for icon requests.
The icon_request.yml template explains the rationale directly:
.github/ISSUE_TEMPLATE/icon_request.yml1-30
Two core constraints drive the policy:
Aggregator model — Nerd Fonts ingests whole icon sets. Adding a lone icon falls outside the normal pipeline, which is documented in Glyph Management.
Codepoint scarcity — Codepoints are a finite resource in the Unicode Private Use Area. Assigning a codepoint to a project that later becomes inactive wastes that slot permanently (or requires a breaking reassignment). See Version History for historical examples of codepoint reassignments.
The recommended path for getting an icon included is:
Request icon → upstream icon set project
↓ (if accepted)
Upstream releases new version
↓
Nerd Fonts updates its bundled copy
↓
Icon appears in Nerd Fonts
Upstream projects apply their own acceptance criteria, which typically require an icon to be widely needed — not specific to a single niche project or distribution.
Decision flow for icon requests:
Sources: .github/ISSUE_TEMPLATE/icon_request.yml1-30
icon_request.yml Issue TemplateThe template is located at .github/ISSUE_TEMPLATE/icon_request.yml and defines the structured fields a requester must fill in.
| Field | Type | Purpose |
|---|---|---|
Requirements | Checkboxes | Confirm the requester searched existing open and closed issues, and checked the suggestion list discussion thread |
Justification | Textarea | Explain why the "no individual icons" convention should be bypassed. Must include links to upstream icon set issues/PRs where the request was declined |
Description | Textarea | Name, links, and ideally an image of the requested icon |
Use scenario | Textarea | Concrete description of how the icon will be used |
Icon license | Input | SPDX license identifier or description for the icon's source files |
.github/ISSUE_TEMPLATE/icon_request.yml31-57
Sources: .github/ISSUE_TEMPLATE/icon_request.yml31-57
The template's Justification field asks for evidence that the normal upstream path was attempted and failed. A strong request includes:
An icon request that does not meet these criteria is unlikely to be accepted regardless of how popular the underlying tool is.
Sources: .github/ISSUE_TEMPLATE/icon_request.yml1-57 readme.md637-643
Refresh this wiki
This wiki was recently refreshed. Please wait 3 days to refresh again.