This page documents the comprehensive changelog system used by Nerd Fonts to track breaking changes, new features, and bug fixes across all releases. The project follows Semantic Versioning 2.0.0 to communicate the nature and impact of changes between versions.
For information about current font versions and metadata, see fonts.json Schema. For information about contributing changes, see Contributing.
The version history system serves several purposes:
The authoritative version history is maintained in changelog.md1-930 and follows a consistent structure across all releases since v0.1.0 (initial release) through v3.4.0 (current).
Sources: changelog.md1-930 package.json1-35 readme.md658-660
The project declares "version": "3.4.0" in package.json3 and follows Semantic Versioning 2.0.0 as declared at the top of changelog.md1-3
MAJOR.MINOR.PATCH bump rules:
| Bump | When | Examples |
|---|---|---|
| MAJOR | Incompatible/breaking changes | Codepoint relocations, font naming overhaul |
| MINOR | Backwards-compatible new features | New fonts, new icon sets, new patcher flags |
| PATCH | Backwards-compatible bug fixes | Glyph corrections, metadata fixes, ligature removals |
Diagram: Versioning decisions mapped to changelog categories
Sources: changelog.md1-3 package.json3
The authoritative version history is maintained in changelog.md and follows a consistent structure. Each version block uses the following Markdown pattern:
## vX.Y.Z
<release description>
### Breaking
- <description> #<issue>
### Fonts
- Add <FontName> @<contributor> #<PR>
- Update <FontName> to <version> #<PR>
### Icons
- Add/Update <icon description> #<PR>
### Features
- <feature description> #<PR>
### Bugs and improvements
- Fix <issue description> #<PR>
### Website and docs
- <documentation updates>
Diagram: changelog.md version block structure and file-level version metadata
Attribution in each entry uses @username for contributors and #number for pull requests or issues.
Sources: changelog.md1-10 package.json1-5 changelog.md45-93
The following table summarizes all breaking changes across releases, drawn directly from the ### Breaking sections of changelog.md:
| Version | Breaking Change | Impact |
|---|---|---|
| v3.4.0 | Remove --use-single-width-glyphs patcher option | Use -s / --mono instead |
| v3.3.0 | Devicons fork switch — old icons dropped | Switched from unmaintained repo to devicons/devicon; some codepoints lost |
| v3.2.1 | Reorder 12 new FontAwesome codepoints (relative to 3.2.0) | See codepoint shift table in changelog.md103-124 |
| v3.0.0 | Complete font naming scheme overhaul | All font names changed; filename spaces removed; Complete dropped |
| v3.0.0 | Material Design Icons codepoints relocated | F500–FD46 (nf-mdi-*) → F0001+ (nf-md-*) |
| v3.0.0 | Windows Compatible variants dropped | All fonts now work cross-platform in a single file |
| v2.0.0 | Font Linux renamed to Font Logos | CSS class names changed |
Sources: changelog.md11-12 changelog.md54-55 changelog.md127-129 changelog.md278-295
Diagram: Major milestones by release
Sources: changelog.md745-930 changelog.md550-745 changelog.md274-550 changelog.md1-274
The v3.0.0 release introduced the most significant breaking change in the project's history — a complete font naming restructure implemented in FontnameParser (see page 2.3). The logic resides in bin/scripts/name_parser/FontnameParser.py and bin/scripts/name_parser/FontnameTools.py
Diagram: Font name transformation (before → after v3.0.0)
Key changes (changelog.md278-286):
Complete moniker dropped — complete is the new defaultWindows Compatible variantsBold Nerd Font → Nerd Font Bold)Nerd Font abbreviated to NF / Nerd Font Mono to NFM when name would be too longSources: changelog.md278-286
The MDI migration was staged across multiple releases. The old codepoints (F500–FD46) conflicted with Asian Unicode blocks; issue #365 tracked the full discussion.
Diagram: MDI codepoint migration path across versions
Migration stages (changelog.md287-295 changelog.md406-413):
F0001+ introduced via PR #773)F500–FD46) and class names (nf-mdi-*) permanently droppedUsers needed to update:
i_*.sh glyph variable filesA translation table between old and new codepoints was published in issue #1059 comment (referenced at changelog.md294).
Sources: changelog.md287-295 changelog.md365-417
Each font update in changelog.md follows the format:
- Update <FontName> to <upstream-version> #<PR>
- Update <FontName> to <upstream-version> @<contributor> #<PR>
Example entries from v3.4.0 (changelog.md18-27):
- Update Cascadia Code to 2407.24 #1844
- Update Iosevka to 33.2.1 #1845
- Update Monaspace to 1.200 #1846
- Update MPlus to 1.007 #1842
Diagram: Font version tracking across files
Font version numbers appear in:
changelog.md: human-readable announcementsbin/scripts/lib/fonts.json: "version" field per font entry (see page 8.1)src/unpatched-fonts/<FontName>/: updated font binary filesSources: changelog.md14-27 changelog.md141-165
The project tracks icon set additions and updates separately from fonts:
| Icon Set | Initial Version | Current Status | Codepoint Range |
|---|---|---|---|
| Powerline | v0.1.0 | Core set, regularly adjusted | E0A0-E0D4 |
| Font Awesome | v0.4.0 | Updated to v6.5.1 (partial) in v3.2.0 | F000+ |
| Octicons | v0.4.0 | Updated to v18.3.0 in v3.0.0 | F400+ |
| Font Awesome Extension | v1.0.0 | 170+ glyphs | Various |
| IEC Power Symbols | v1.0.0 | Stable | 23FB-23FE |
| Font Linux/Logos | v0.8.0 | Updated to v1.3.0 in v3.3.0 | F300+ |
| Pomicons | v0.3.0 | Stable | E000+ |
| Devicons | v0.3.0 | Switched to fork in v3.3.0 | E700+ |
| Material Design Icons | v2.0.0 | 2000+ icons, relocated in v3.0.0 | F0001+ |
| Weather | v2.0.0 | Stable | E300+ |
| Codicons | v2.2.0 | Updated to v0.0.35 in v3.2.0 | EA60+ |
Sources: changelog.md1-930 readme.md97
Sources: changelog.md319-333 changelog.md369-373 changelog.md29-37
The changelog is updated manually as part of each release. Version metadata is synchronised across three files:
Diagram: Files updated at each release
Sources: changelog.md1-5 package.json1-5
For the v3.0.0 breaking changes, the project provided:
nerdfix: Referenced in changelog.md242 for automated icon reference updates in config filesF500–FD46) and new (F0001+) MDI codepoints, giving users time to migrate (changelog.md406-413)v3.2.1 corrected a collision between newly introduced FontAwesome glyphs and Fira Code progress indicator codepoints (EE00–EE08). The full shift table is at changelog.md103-124:
| Glyph name | v3.2.0 | v3.2.1 |
|---|---|---|
fa_less_than | EE00 | EFC3 |
fa_memory | EE02 | EFC5 |
fa_not_equal | EE08 | EFCB |
fa_palette | EE09 | EFCC |
| (and 8 others) |
Beginning with v2.3.0, the project adopted a stable codepoints policy (changelog.md384 PR #778): once a glyph is assigned a codepoint it will not move unless a conflict with an established Unicode block requires it (as happened with MDI at F500–FD46).
Sources: changelog.md94-130 changelog.md240-244 changelog.md380-390
Version information is stored in multiple locations across the repository:
| File | Purpose | Format | Updated |
|---|---|---|---|
| changelog.md | Full human-readable history | Markdown | Every release |
| package.json3 | Overall project version ("version": "3.4.0") | JSON | Every release |
| bin/scripts/lib/fonts.json | Per-font version field | JSON | When individual fonts update |
font-patcher script header | Embedded patcher version string | Python comment | Every release |
| Patched font SFNT tables | Version name table entry in each font | Binary | During patching |
The package.json "version" field (package.json3) is the canonical project-level version identifier. The "version" field in each entry of bin/scripts/lib/fonts.json tracks the upstream version of that specific font family, independent of the Nerd Fonts project version.
Sources: package.json1-5 changelog.md1-5
The latest release demonstrates the current changelog structure:
Breaking Changes:
--use-single-width-glyphs (replaced by -s or --mono)New Fonts:
Font Updates (10 fonts):
Icon Additions:
Features:
--cellFixes:
fsSelection handling for proportional fontsSources: changelog.md5-44
Refresh this wiki
This wiki was recently refreshed. Please wait 3 days to refresh again.