# 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):**

```bash
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

| Requirement | Detail |
|---|---|
| OS | Windows, macOS, Linux, ChromeOS, or any system supporting OpenType fonts |
| Font format support | OTF, TTF, WOFF, WOFF2 (variable TTF for advanced use) |
| Editor requirement | Must support OpenType ligatures (`calt` feature) |

### Installation Methods

=== "macOS (Homebrew)"
    ```bash
    brew install --cask font-fira-code
    ```

=== "Linux (apt)"
    ```bash
    sudo apt install fonts-firacode
    ```

=== "Fedora/RHEL"
    ```bash
    sudo dnf install fira-code-fonts
    ```

=== "Arch Linux"
    ```bash
    sudo pacman -S ttf-fira-code
    ```

=== "Chocolatey (Windows)"
    ```bash
    choco install firacode
    ```

=== "Scoop (Windows)"
    ```bash
    scoop bucket add nerd-fonts
    scoop install firacode
    ```

=== "npm (web projects)"
    ```bash
    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:

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

### Available Font Files

| Format | Directory | Use Case |
|---|---|---|
| OTF (static) | `distr/otf/` | Desktop apps, print |
| TTF (static) | `distr/ttf/` | Desktop apps, general use |
| Variable TTF | `distr/variable_ttf/` | Apps supporting variable fonts (continuous weight) |
| WOFF | `distr/woff/` | Web (legacy browser fallback) |
| WOFF2 | `distr/woff2/` | Web (modern browsers, best compression) |

### Font Weights

| Weight | File Suffix | Description |
|---|---|---|
| Light | `-Light` | Thin strokes for high-DPI displays |
| Regular | `-Regular` | Default weight |
| Retina | `-Retina` | Slightly heavier than Regular, optimized for Retina screens |
| Medium | `-Medium` | Between Regular and SemiBold |
| SemiBold | `-SemiBold` | Semi-bold weight |
| Bold | `-Bold` | Full bold weight |

> [!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:**
```bash
fc-list | grep "Fira Code"
```

**Linux:**
```bash
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`:

```css
@import url('fira_code.css');

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

For self-hosted WOFF2:

```css
@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.

| Editor | Setting |
|---|---|
| **VS Code** | `"editor.fontFamily": "Fira Code"`, `"editor.fontLigatures": true` |
| **JetBrains IDEs** | Settings → Editor → Font → **Fira Code**, check **Enable ligatures** |
| **Sublime Text** | `"font_face": "Fira Code"`, `"font_options": ["gray_antialias", "subpixel_antialias"]` |
| **Vim/Neovim (GUI)** | `set guifont=Fira\ Code:h12` (ligatures depend on terminal/GUI support) |
| **Emacs** | `(set-frame-font "Fira Code 12" nil t)` + enable `prettify-symbols-mode` or use `fira-code-mode` |
| **Terminal (macOS)** | iTerm2: Profiles → Text → Font → **Fira Code**, check **Use ligatures** |
| **Windows Terminal** | `"font": { "face": "Fira Code" }` in `settings.json` |

> [!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:

```json
"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:

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

### Old-Style Numerals

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

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

### Zero Style

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

```json
"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:**
```text
->  -->  ->>  =>  ==>  =>>  <-  <--  <<-  <=  <==  <<=  <->  <-->  <=>  <==>
```

**Comparison and equality:**
```text
==  ===  !=  !==  >=  <=  <>
```

**Logical operators:**
```text
&&  ||  |||  !!
```

**Pipes and composition:**
```text
|>  <|  ||>  <||  |||>  <|||  >>  <<  >>>  <<<
```

**Comments:**
```text
//  /*  */
```

**String and assignment:**
```text
::  :=  ..  ...  ++  --
```

**Haskell / functional:**
```text
>>=  =<<  <*>  <+>  <$>
```

**Math and comparison:**
```text
<=  >=  /=  ~=
```

### 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:
   ```bash
   npm install firacode
   ```

2. Import the CSS in your stylesheet:
   ```css
   @import url('node_modules/firacode/distr/fira_code.css');
   ```

3. Apply to code elements:
   ```css
   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/`:
   ```css
   @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):
   ```css
   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:

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

Or disable all ligatures while keeping the font:

```json
"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:
   ```bash
   cd script
   ./build.sh -f cv01,cv02,ss01
   ```

2. Optionally set a custom family name:
   ```bash
   ./build.sh -f cv01,cv02 -n "Fira Code Custom"
   ```

3. Use `-g` to generate only the `.glyphs` file without compiling fonts:
   ```bash
   ./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.

```bash
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

| Display Type | Recommended Weight |
|---|---|
| Standard LCD (1080p) | Regular |
| Retina/HiDPI (macOS) | Retina or Light |
| 4K displays | Light |
| Presentations/demos | Bold or SemiBold |
| Print | Regular or Medium |

## 6. Troubleshooting

### Diagnostic Decision Tree

```text
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:
   ```bash
   docker build -t tonsky/firacode .
   ```
2. Verify the volume mount path is correct (must be absolute):
   ```bash
   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:**
```bash
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.

---

_Generated May 2026 from tonsky/FiraCode at d0cf393. AI-generated documentation. The library is checked by sampling (three repositories so far); this guide was not individually reviewed. Verify against the project before relying on it. Unofficial; not affiliated with or reviewed by the project._