Fira Code — User Guide

1. Quick Start

Fira Code is a free, open-source monospaced font designed for programming. It extends the excellent Fira Mono with programming ligatures — contextual substitutions that render multi-character sequences like =>, ->, !=, and >= as single typographic symbols, improving code readability without changing the underlying characters.

Key features:

• Programming ligatures for 100+ common operator sequences (arrows, comparisons, logical operators, pipes)
• 6 font weights: Light, Regular, Retina, Medium, SemiBold, Bold
• Variable font (VF) for continuous weight axis
• 32 character variants (cv01–cv32) for individual glyph customization
• 10 stylistic sets (ss01–ss10) for grouped alternate styles
• Old-style numerals (onum) feature
• Web font support (WOFF, WOFF2, CSS)
• Available via all major package managers and Google Fonts
• Licensed under SIL Open Font License 1.1

Prerequisites: Any operating system with font installation support.

Fastest install (Homebrew on macOS):

brew install --cask font-fira-code

Open your editor, set the font to Fira Code, enable ligatures, and start coding.

Tip

If you just want to try Fira Code quickly, visit the specimen page in the distr/specimen.html file or preview it on Google Fonts — no installation needed.

2. Installation

System Requirements

Installation Methods

macOS (Homebrew)

brew install --cask font-fira-code

Linux (apt)

sudo apt install fonts-firacode

Fedora/RHEL

sudo dnf install fira-code-fonts

Arch Linux

sudo pacman -S ttf-fira-code

Chocolatey (Windows)

choco install firacode

Scoop (Windows)

scoop bucket add nerd-fonts
scoop install firacode

npm (web projects)

npm install firacode

Manual Installation

1. Download the latest release ZIP from the GitHub releases page
2. Extract the archive
3. Install the font files for your platform:

Windows: Right-click the .ttf or .otf files → Install (or Install for all users)

macOS: Double-click each font file → click Install Font in Font Book

Linux: Copy font files to ~/.local/share/fonts/ then refresh the cache:

cp distr/ttf/FiraCode-*.ttf ~/.local/share/fonts/
fc-cache -fv

Available Font Files

Font Weights

Important

The Retina weight is excluded from WOFF and WOFF2 web font distributions. It is available only in OTF and TTF static formats. The variable font also excludes Retina (it is disabled during variable font generation).

Post-Install Verification

After installation, verify the font is available:

macOS:

fc-list | grep "Fira Code"

Linux:

fc-list | grep "Fira Code"

Windows: Open Settings → Fonts and search for "Fira Code."

Web Usage (CSS)

Include the distributed CSS file or use a CDN. The package distributes a ready-made CSS file at distr/fira_code.css:

@import url('fira_code.css');

code {
  font-family: 'Fira Code', monospace;
}

For self-hosted WOFF2:

@font-face {
  font-family: 'Fira Code';
  src: url('FiraCode-Regular.woff2') format('woff2'),
       url('FiraCode-Regular.woff') format('woff');
  font-weight: 400;
  font-style: normal;
}

Note

The npm package (firacode) exposes only the distr/ directory. After npm install firacode, font files are at node_modules/firacode/distr/.

3. Configuration

Enabling Ligatures in Your Editor

Fira Code ligatures use the OpenType calt (Contextual Alternates) feature. Most modern editors support this, but it may need to be explicitly enabled.

Warning

Not all terminals support ligatures. Standard macOS Terminal.app and many Linux terminal emulators do not render ligatures. Use iTerm2, Kitty, Alacritty (with config), or Windows Terminal for full ligature support.

Character Variants (cv01–cv32)

Character variants let you customize individual glyphs without changing the overall font. Enable them through your editor's OpenType feature settings.

VS Code example — enable specific character variants:

"editor.fontLigatures": "'calt' on, 'cv01' on, 'cv02' on"

JetBrains example — use the Typography Settings panel under Editor → Font to toggle individual variants.

Tip

Character variants are independent — you can mix and match any combination. Use the specimen page (distr/specimen.html) to preview all variants before choosing.

Stylistic Sets (ss01–ss10)

Stylistic sets apply grouped alternate styles that change multiple related glyphs at once. Each set has a descriptive label in the font metadata.

Enable in VS Code:

"editor.fontLigatures": "'ss01' on, 'ss05' on"

Old-Style Numerals

The onum feature switches to old-style (lowercase) numerals where digits have varying heights:

"editor.fontLigatures": "'onum' on"

Zero Style

The zero feature provides a slashed or dotted zero for distinguishing 0 from O:

"editor.fontLigatures": "'zero' on"

Note

See the Admin Guide for the full configuration reference covering all 32 character variants, 10 stylistic sets, calt sub-features, and glyph class definitions.

4. Core Usage

How Ligatures Work

Fira Code ligatures are purely visual — they do not change the underlying text. When you type ->, the font renders it as a single arrow glyph, but copying the text still produces the two characters - and >. This means:

• Ligatures work in any application that supports OpenType calt
• No special keyboard input required — just type normally
• Code search, copy-paste, and version control are unaffected
• Cursor movement steps through each original character

Common Ligature Categories

Arrows:

->  -->  ->>  =>  ==>  =>>  <-  <--  <<-  <=  <==  <<=  <->  <-->  <=>  <==>

Comparison and equality:

==  ===  !=  !==  >=  <=  <>

Logical operators:

&&  ||  |||  !!

Pipes and composition:

|>  <|  ||>  <||  |||>  <|||  >>  <<  >>>  <<<

Comments:

//  /*  */

String and assignment:

::  :=  ..  ...  ++  --

Haskell / functional:

>>=  =<<  <*>  <+>  <$>

Math and comparison:

<=  >=  /=  ~=

Ligature Interaction Rules

The font includes carefully crafted ignore rules to prevent unwanted ligatures in specific contexts:

• Regex lookahead/lookbehind patterns: (?=, (?!, (?<=, (?<! — these are NOT ligated (issues #578, #624)
• PHP opening tag with assignment: <?= — not ligated (issue #850)
• Lua-style bracket equality: [==[, ]==], [==, ==] — not ligated (issues #948, #968)
• Haskell bind operators >>= and <<= are preserved when adjacent to other operators (issue #974)
• Block comment boundaries /* */ prevent false ligatures within /***/ sequences
• Bracket-pipe combinations {|}, [|] are not ligated (issue #593)
• Compound operators like =:=, =!= do not double-ligate (issue #346)
• //= does not falsely trigger (issue #816)
• Pipe-angle combinator <||> prevents incorrect partial ligation (issue #621)
• Haskell-style operators <*>>, <<*>, <+>>, <<+>, <$>>, <<$> are handled correctly (issue #410)

Tip

If a specific ligature causes problems in your programming language, you can disable individual ligatures by turning off specific character variants or stylistic sets in your editor's font settings.

5. Common Tasks

Task: Use Fira Code for Web Development

Goal: Add Fira Code to a website's code blocks.

Steps:

1. Install via npm:

   npm install firacode
   

2. Import the CSS in your stylesheet:

   @import url('node_modules/firacode/distr/fira_code.css');
   

3. Apply to code elements:

   pre, code {
     font-family: 'Fira Code', monospace;
     font-feature-settings: "calt" on;
   }
   

4. Verify by loading a page with code blocks — ligatures like => and -> should render as combined glyphs.

Task: Use the Variable Font for Fine-Grained Weight Control

Goal: Use a single font file with adjustable weight axis.

1. Use the variable font from distr/variable_ttf/:

   @font-face {
     font-family: 'Fira Code VF';
     src: url('FiraCode-VF.ttf') format('truetype');
     font-weight: 300 700;
   }
   

2. Set any weight value between 300 (Light) and 700 (Bold):

   code { font-variation-settings: 'wght' 450; }
   

Task: Disable Specific Ligatures

Goal: Keep most ligatures but turn off a few that conflict with your language.

In VS Code, use selective feature toggling:

"editor.fontLigatures": "'calt' on, 'ss01' off"

Or disable all ligatures while keeping the font:

"editor.fontLigatures": false

Task: Build a Custom Font with Specific Features Baked In

Goal: Generate a custom Fira Code variant with specific OpenType features permanently enabled.

Prerequisites: Clojure runtime, Python 3 with font build tools.

1. Run the build script with the -f flag to bake in specific features:

   cd script
   ./build.sh -f cv01,cv02,ss01
   

2. Optionally set a custom family name:

   ./build.sh -f cv01,cv02 -n "Fira Code Custom"
   

3. Use -g to generate only the .glyphs file without compiling fonts:

   ./build.sh -f cv01 -g
   

4. Output appears in distr/ subdirectories (OTF, TTF, variable, WOFF, WOFF2).

Warning

Custom builds require a full build environment (Python with fontmake, gftools, ttfautohint, woff2, sfnt2woff-zopfli). See the Admin Guide for complete build setup instructions.

Task: Build from Source Using Docker

Goal: Build the font without installing build dependencies locally.

docker build -t tonsky/firacode .
docker run --rm -v $(pwd):/opt/FiraCode tonsky/firacode ./FiraCode/script/build

The built fonts appear in the distr/ directory.

Task: Select the Right Weight for Your Display

6. Troubleshooting

Diagnostic Decision Tree

Ligatures not showing?
├── Is the font installed? → Verify in system font settings
│   └── No → Install Fira Code (see Section 2)
├── Is the correct font selected? → Check editor font setting shows "Fira Code"
│   └── "Fira Mono" or "Fira Sans" selected → Change to "Fira Code"
├── Are ligatures enabled? → Check editor ligature settings
│   └── No → Enable (see Section 3)
└── Does your terminal support ligatures?
    └── No → Switch to iTerm2, Kitty, Windows Terminal, or Alacritty

Error: Font Not Appearing in Windows Console Font List

Cause: Windows Console (conhost) has strict requirements for monospace fonts and may not list Fira Code.

Solution:

1. Use Windows Terminal instead of the legacy console — it fully supports Fira Code
2. If you must use the legacy console, ensure you have installed the TTF version (not OTF)
3. Check that the font is installed system-wide ("Install for all users"), not per-user

Prevention: Always prefer Windows Terminal for modern font support. (Community issue #1409)

Error: Ligatures Not Rendering in Terminal

Cause: Many terminal emulators do not support OpenType contextual alternates.

Solution:

1. Switch to a ligature-capable terminal (iTerm2, Kitty, Alacritty, Windows Terminal, Hyper)
2. Ensure the terminal's font settings explicitly enable ligatures if the option exists
3. For iTerm2: Profiles → Text → check Use ligatures

Prevention: Check your terminal's documentation for ligature support before expecting them.

Error: Docker Build Fails

Cause: Docker environment or volume mount issues during custom font builds.

Solution:

1. Ensure Docker is running and the Dockerfile builds successfully:

   docker build -t tonsky/firacode .
   

2. Verify the volume mount path is correct (must be absolute):

   docker run --rm -v "$(pwd)":/opt/FiraCode tonsky/firacode ./FiraCode/script/build
   

3. Check that you have write permissions to the distr/ directory

Prevention: Use absolute paths for Docker volume mounts. (Community issue #1653)

Error: Misaligned Glyphs with Certain Character Sequences

Cause: Some complex template syntax combinations (like ClassName<type>::Function) can cause visual misalignment.

Solution:

1. Update to the latest version of Fira Code
2. Check if the issue occurs with specific character variant settings
3. Disable the problematic ligature via font feature settings if needed

Prevention: Report alignment issues on GitHub with screenshots and the exact character sequence. (Community issue #1684)

Error: Box Drawing Characters Broken in Italic

Cause: Box drawing ligatures can render incorrectly when italic style is applied.

Solution: Use the upright (Roman) style for content that includes box-drawing characters. Most terminals default to upright for box-drawing ranges.

Prevention: Avoid applying italic to box-drawing character ranges in your editor theme. (Community issue #1662)

Warning

Supplemental Arrows-B glyphs (U+2900–U+297F) may exceed the monospace cell width in some environments, causing alignment issues. This is a known limitation. (Community issue #1677)

Error: Can't identify version During Custom Build

Cause: The script/common.py version helper could not determine the version from either the --version CLI flag or the GITHUB_REF environment variable.

Solution:

cd script
python3 release.py --version 6.2

Prevention: Always pass --version explicitly when running release or build scripts outside of GitHub Actions.

Caution

The release script publishes to GitHub Releases and requires authentication via API_TOKEN, GITHUB_TOKEN, or GITHUB_BASIC environment variable. Running it accidentally can create unintended releases.

7. FAQ

Q: Does Fira Code change the actual characters in my code?

No. Ligatures are purely visual rendering — the underlying characters remain unchanged. Copy-paste, search, version control, and compilers all see the original characters.

Q: Can I use Fira Code in commercial projects?

Yes. Fira Code is licensed under the SIL Open Font License 1.1, which permits free use in commercial and non-commercial projects, including embedding in applications and documents.

Q: What is the difference between Fira Code and Fira Mono?

Fira Mono is the original Mozilla monospace font without ligatures. Fira Code extends Fira Mono by adding programming ligatures and additional character variants. If you want ligatures, use Fira Code.

Q: Does Fira Code work with all programming languages?

Fira Code ligatures cover common operators from most programming languages including JavaScript, TypeScript, Python, Haskell, Rust, Go, C/C++, Ruby, Elixir, and many others. Some language-specific operators may not have ligatures; you can request new ones via GitHub issues.

Q: Why are some ligatures not appearing for specific character combinations?

The font includes deliberate ignore rules to prevent incorrect ligatures in regex patterns, PHP tags, Lua bracket equality, and other contexts where ligating would be wrong. See the "Ligature Interaction Rules" section for details.

Q: When is the next version coming out?

The project version is 6.2.0. Development is ongoing but release timing is at the maintainer's discretion. (Community issue #1680)

Q: Can I request new glyphs or ligatures?

Yes. Feature requests for new glyphs (e.g., Unicode symbols like ⇱⇲⊞❖ in #1673, Hebrew character support in #1658) and new ligatures (e.g., =? and =?= in #1563) are accepted via GitHub issues.

Q: How do I use Fira Code in the Zed editor?

Set the font family in Zed's settings to "Fira Code". Zed supports OpenType ligatures natively. (Community issue #1652)

Q: Can I get old-style (lowercase) numerals?

Yes. Enable the onum OpenType feature in your editor's font settings. In VS Code: "editor.fontLigatures": "'onum' on".

Q: Is there a Typst-compatible stylistic set?

Not yet — this is a requested feature (community issue #1671). Monitor the GitHub issues for updates.