Export translations

Settings

Group

Language

Format

Export for off-line translation

Export in native format

Export in CSV format

<languages/>
<div lang="en" dir="ltr" class="mw-content-ltr">
NixOS handles fonts like it handles many different parts of the system: they are not in an environment unless explicitly marked to be part of it. This guide covers the installation, configuration and troubleshooting of fonts.
</div>

<span lang="en" dir="ltr" class="mw-content-ltr">== Installing fonts on NixOS ==</span>

<span lang="en" dir="ltr" class="mw-content-ltr">NixOS has many font packages available, and you can easily search for your favorites on the</span> [https://search.nixos.org/packages NixOS packages site].

<span lang="en" dir="ltr" class="mw-content-ltr">Despite looking like normal packages, simply adding these font packages to your <code>environment.systemPackages</code> won't make the fonts accessible to applications. To achieve that, put these packages in the <code>[https://search.nixos.org/options?channel=unstable&show=fonts.packages&from=0&size=50&sort=relevance&type=packages&query=fonts.packages fonts.packages]</code> NixOS options list instead.</span>

''For example:''

{{File|3=fonts.packages = with pkgs; [
  noto-fonts
  noto-fonts-cjk-sans
  noto-fonts-color-emoji
  liberation_ttf
  fira-code
  fira-code-symbols
  mplus-outline-fonts.githubRelease
  dina-font
  proggyfonts
];|name=/etc/nixos/configuration.nix|lang=nix}}{{Note|Be aware that sometimes font names and packages name differ and there is no universal convention in NixOS. </br>See: [https://discourse.nixos.org/t/guidelines-on-packaging-fonts/7683/2 Guidelines for font packaging]}}

<span lang="en" dir="ltr" class="mw-content-ltr">=== Shorthands for fonts ===</span>
<div lang="en" dir="ltr" class="mw-content-ltr">
* <code>fonts.enableDefaultPackages</code>: when set to <code>true</code>, causes some "basic" fonts to be installed for reasonable Unicode coverage. Set to <code>true</code> if you are unsure about what languages you might end up reading.
* <code>fonts.enableGhostscriptFonts</code>: affects the <code>ghostscript</code> package. Ghostscript packages some URW fonts for the standard PostScript typefaces. If <code>true</code>, these fonts will be visible to GUI applications. You could set it to <code>true</code> if you want these fonts, but <code>gyre-fonts</code> (part of <code>fonts.enableDefaultPackages</code>) might be higher-quality depending on your judgement.
</div>

<span lang="en" dir="ltr" class="mw-content-ltr">=== Using fonts from TexLive ===</span>
<div lang="en" dir="ltr" class="mw-content-ltr">
You can make use of all TeX/LaTeX fonts from CTAN and [[TexLive]] by passing
the <code>fonts</code> attribute of your TexLive package to <code>fonts.package</code>:
</div>

{{File|3={ pkgs, ... }:
let
  mytex =
    pkgs.texliveConTeXt.withPackages
      (ps: with ps; [ 
        fandol
        libertinus-fonts
      ]);
in {
  fonts.packages = builtins.attrValues {
    inherit (pkgs)
      dejavu_fonts 
      noto-fonts-cjk-serif
      noto-fonts-cjk-sans
      julia-mono;
  } ++ [ mytex.fonts ];
}|name=/etc/nixos/configuration.nix|lang=nix}}

<span lang="en" dir="ltr" class="mw-content-ltr">=== Installing <code>nerdfonts</code> ===</span>

<div lang="en" dir="ltr" class="mw-content-ltr">
Individual Nerd Fonts can be installed like so:
</div>

{{File|3=fonts.packages = with pkgs; [
  nerd-fonts.fira-code
  nerd-fonts.droid-sans-mono
];|name=/etc/nixos/configuration.nix|lang=nix}}

<div lang="en" dir="ltr" class="mw-content-ltr">
The available Nerd Font subpackages can be listed by searching for {{nixos:package|nerd-fonts.*}} on the [[Searching packages|NixOS Package Search]] or by running the following command: <syntaxhighlight lang="console">
$ nix-instantiate --eval --expr "with (import <nixpkgs> {}); lib.attrNames (lib.filterAttrs (_: lib.isDerivation) nerd-fonts)"
</syntaxhighlight>
</div>

<div lang="en" dir="ltr" class="mw-content-ltr">
==== Installing all <code>nerdfonts</code> ====
</div>

<div lang="en" dir="ltr" class="mw-content-ltr">
Installing all fonts from the [https://www.nerdfonts.com/ Nerd Fonts repository] is as simple as adding all of the individual packages to the NixOS configuration. The following line will do exactly that, by searching for all derivations under the <code>nerd-font</code> attribute:{{file|||<nowiki>
{ 
  fonts.packages = builtins.filter lib.attrsets.isDerivation (builtins.attrValues pkgs.nerd-fonts);
}
</div>

<div lang="en" dir="ltr" class="mw-content-ltr">
# or if you already have fonts.packages set
</div>

<div lang="en" dir="ltr" class="mw-content-ltr">
{
  fonts.packages = [
     # ... some fonts
  ] 
  ++ builtins.filter lib.attrsets.isDerivation (builtins.attrValues pkgs.nerd-fonts);
}
</nowiki>|name=/etc/nixos/configuration.nix|lang=nix}}
</div>

<span lang="en" dir="ltr" class="mw-content-ltr">=== Patching nerdfonts into fonts ===</span>
<div lang="en" dir="ltr" class="mw-content-ltr">
Not all fonts have Nerd Fonts variants, thankfully you can easily patch them in yourself.
{{File|3=(pkgs.scientifica.overrideAttrs (o: {
  nativeBuildInputs = [ pkgs.nerd-font-patcher ];
  postInstall = ''
    mkdir -p $out/share/fonts/truetype/{scientifica,scientifica-nerd}
    mv $out/share/fonts/truetype/*.ttf $out/share/fonts/truetype/scientifica/
    for f in $out/share/fonts/truetype/scientifica/*.ttf; do
      nerd-font-patcher --complete --outputdir $out/share/fonts/truetype/scientifica-nerd/ $f
    done
  '';
}))|name=/etc/nixos/configuration.nix|lang=nix}}
</div>

<span lang="en" dir="ltr" class="mw-content-ltr">=== Let Fontconfig know the fonts within your Nix profile ===</span>
<div lang="en" dir="ltr" class="mw-content-ltr">
Nix inserts its user profile path into <code>$XDG_DATA_DIRS</code>, which Fontconfig by default doesn't look in. This cause graphical applications like KDE Plasma not able to recognize the fonts installed via <code>nix-env</code> or <code>nix profile</code>.
</div>

<div lang="en" dir="ltr" class="mw-content-ltr">
To solve this, add the file <code>100-nix.conf</code> to your Fontconfig user configuration directory (usually <code>$XDG_CONFIG_HOME/fontconfig/conf.d</code>):
<syntaxhighlight lang="xml">
<?xml version="1.0"?>
<!DOCTYPE fontconfig SYSTEM "urn:fontconfig:fonts.dtd">
<fontconfig>
  
  <dir>NIX_PROFILE/lib/X11/fonts</dir>
  <dir>NIX_PROFILE/share/fonts</dir>
</fontconfig>
</syntaxhighlight>
and run <code>fc-cache</code>.
</div>

<div lang="en" dir="ltr" class="mw-content-ltr">
Alternatively, [https://nix-community.github.io/home-manager/options.xhtml#opt-fonts.fontconfig.enable enable Fontconfig configuration] in your Home Manager configuration.
</div>

<span lang="en" dir="ltr" class="mw-content-ltr">=== Imperative installation of user fonts ===</span>
<span lang="en" dir="ltr" class="mw-content-ltr">This is useful for quick font experiments.</span>

''Example'': Install <code>SourceCodePro-Regular</code>.
<syntaxhighlight lang="bash">font=$(nix-build --no-out-link '<nixpkgs>' -A source-code-pro)/share/fonts/opentype/SourceCodePro-Regular.otf
cp $font ~/.local/share/fonts
fc-cache
# Verify that the font has been installed
fc-list -v | grep -i source
</syntaxhighlight>

<span lang="en" dir="ltr" class="mw-content-ltr">=== Install fonts in nix-shells ===</span>

<div lang="en" dir="ltr" class="mw-content-ltr">
<code>fonts</code> is not available as set-valued option in <code>mkshell</code> (gives you an error because it tries to coerce an attribute set into a string). Instead, insert the following:
</div><ref>https://programming.dev/post/32484220</ref>

<div lang="en" dir="ltr" class="mw-content-ltr">
<syntaxhighlight lang="nix">
{pkgs ? import <nixpkgs> {} }:
let
  fontsConf = pkgs.makeFontsConf {
    fontDirectories = [
      # your needed fonts here, e.g.:
      pkgs.font-awesome
      pkgs.atkinson-hyperlegible-next
    ];
  };
in
  pkgs.mkShell {
    packages = with pkgs; [
      # your font-dependent packages, e.g.:
      typst
    ];
    shellHook = ''
      export FONTCONFIG_FILE="${fontsConf}"
    '';
  }
</syntaxhighlight>
Then <code>typst fonts</code> finds the installed fonts in the nix-shell.
</div>

<span lang="en" dir="ltr" class="mw-content-ltr">== Configuring fonts ==</span>

<div lang="en" dir="ltr" class="mw-content-ltr">
The nixos key [https://search.nixos.org/options?channel=unstable&from=0&size=50&sort=relevance&type=packages&query=fonts.fontconfig <code>fonts.fontconfig</code>] (click to see the full list!) handles the fontconfig options. Some options are nicely wrapped in nix; there's always <code>localConf</code> to go straight to the XML.
</div>

<span lang="en" dir="ltr" class="mw-content-ltr">=== Set multiple fonts for different languages ===</span>
<div lang="en" dir="ltr" class="mw-content-ltr">
If you want to use other languages alongside English, you may want to set appropriate fonts for each language in your whole OS. For example, a Persian speaker might want to use the
</div> [https://rastikerdar.github.io/vazirmatn/ Vazirmatn] <span lang="en" dir="ltr" class="mw-content-ltr">font for Persian texts, but</span> [https://design.ubuntu.com/font/ Ubuntu] <div lang="en" dir="ltr" class="mw-content-ltr">
and Liberation Serif fonts for English texts. Just put these lines into your <code>configuration.nix</code>:
</div>

<div lang="en" dir="ltr" class="mw-content-ltr">
{{File|3=#----=[ Fonts ]=----#
fonts = {
  enableDefaultPackages = true;
  packages = with pkgs; [ 
    ubuntu-classic
    liberation_ttf
    # Persian Font
    vazir-fonts
  ];
</div>

<div lang="en" dir="ltr" class="mw-content-ltr">
fontconfig = {
    defaultFonts = {
      serif = [  "Liberation Serif" "Vazirmatn" ];
      sansSerif = [ "Ubuntu" "Vazirmatn" ];
      monospace = [ "Ubuntu Mono" ];
    };
  };
};|name=/etc/nixos/configuration.nix|lang=nix}}
</div>

<div lang="en" dir="ltr" class="mw-content-ltr">
NB:
* This actually just sets the font fallback order so that fontconfig tries using the English font first, then falls back to another font if the character set is not covered. You ''usually'' want to write the English font ''before'' the other-language font, because the other-language font might cover Latin characters too, preventing the English font from showing up.
* <code>defaultFonts</code> translates to <code>&lt;prefer&gt;</code> in the actual fontconfig file. See https://github.com/NixOS/nixpkgs/blob/nixos-23.11/nixos/modules/config/fonts/fontconfig.nix for how NixOS does it, and the links below for how fontconfig interpret it.
* Vazirmatn is actually a "sans-serif" font; using it for <code>serif</code> is not a good visual match. You might need not one, but two (or if you count monospace, three!) font packages for a language.
</div>

<span lang="en" dir="ltr" class="mw-content-ltr">=== Use custom font substitutions ===</span>

<div lang="en" dir="ltr" class="mw-content-ltr">
Sometimes, documents may appear to have bad kerning or hard-to-read letter spacing, due to a bad substitution.
For example, Okular may show in the ''Document Properties'' dialog that it has substituted DejaVu Sans Mono (a sans-serif font) in place of "NewCenturySchlbk". <code>fc-match NewCenturySchlbk</code> would display similiar info.
</div>

<div lang="en" dir="ltr" class="mw-content-ltr">
Adding this to your <code>/etc/nixos/configuration.nix</code> should prompt it to use the more similar (and nicer) serif ''Schola'' font instead:
</div>

<div lang="en" dir="ltr" class="mw-content-ltr">
{{File|3=fonts = {
  packages = with pkgs; [ gyre-fonts ];
  fontconfig = {
    localConf = ''
      
      <match target="pattern">
        <test qual="any" name="family"><string>NewCenturySchlbk</string></test>
        <edit name="family" mode="assign" binding="same"><string>TeX Gyre Schola</string></edit>
      </match>
    '';
  };
};|name=/etc/nixos/configuration.nix|lang=nix}}
</div>

<div lang="en" dir="ltr" class="mw-content-ltr">
For more information and examples on the xml configuration language:
</div>

* https://www.mankier.com/5/fonts-conf
* https://wiki.archlinux.org/index.php/Font_configuration
* https://wiki.archlinux.org/index.php/Font_configuration/Examples

<div lang="en" dir="ltr" class="mw-content-ltr">
For a list of suitable replacement fonts:
</div>
* https://wiki.archlinux.org/title/Metric-compatible_fonts

<span lang="en" dir="ltr" class="mw-content-ltr">== Troubleshooting ==</span>

<span lang="en" dir="ltr" class="mw-content-ltr">=== What font names can be used in <code>fonts.fontconfig.defaultFonts.monospace</code>? ===</span>

<span lang="en" dir="ltr" class="mw-content-ltr">Those that fontconfig will understand. This can be queried from a font file using <code>fc-query</code>.</span>

<syntaxhighlight lang="console">
$ cd /nix/var/nix/profiles/system/sw/share/X11/fonts
$ fc-query DejaVuSans.ttf | grep '^\s\+family:' | cut -d'"' -f2
</syntaxhighlight>

<div lang="en" dir="ltr" class="mw-content-ltr">
Note that you may need to set <code>fonts.fontDir.enable = true;</code> for that X11/fonts directory to exist.
</div>

<span lang="en" dir="ltr" class="mw-content-ltr">=== Adding personal fonts to <code>~/.fonts</code> doesn't work ===</span>

<div lang="en" dir="ltr" class="mw-content-ltr">
The <code>~/.fonts</code> directory is being deprecated upstream<ref>https://lists.freedesktop.org/archives/fontconfig/2014-July/005269.html</ref>. It already doesn't work in NixOS.
</div>

<div lang="en" dir="ltr" class="mw-content-ltr">
The new preferred location is in <code>$XDG_DATA_HOME/fonts</code>, which for most users will resolve to <code>~/.local/share/fonts</code>
</div><ref>https://lists.freedesktop.org/archives/fontconfig/2014-July/005270.html</ref>

<span lang="en" dir="ltr" class="mw-content-ltr">=== Flatpak applications can't find system fonts ===</span>

<span lang="en" dir="ltr" class="mw-content-ltr">To expose available fonts under <code>/run/current-system/sw/share/X11/fonts</code>, enable <code>fontDir</code> in your NixOS configuration.</span>

{{File|3=fonts.fontDir.enable = true;|name=/etc/nixos/configuration.nix|lang=nix}}

<span lang="en" dir="ltr" class="mw-content-ltr">You will then need to link/copy this folder to one of the Flatpak-supported locations - see below.</span>

<span lang="en" dir="ltr" class="mw-content-ltr">==== Solution 1: Copy fonts to <code>$HOME/.local/share/fonts</code> ====</span>
<div lang="en" dir="ltr" class="mw-content-ltr">
Create fonts directory <code>$HOME/.local/share/fonts</code> and copy system fonts with option <code>-L, --dereference</code>. You will need to repeat this step whenever the fonts change.<syntaxhighlight lang="console">
$ mkdir $HOME/.local/share/fonts && cp -L /run/current-system/sw/share/X11/fonts/* $HOME/.local/share/fonts/
</syntaxhighlight>Note: There is no need to grant flatpak applications access to <code>$HOME/.local/share/fonts</code>.
</div>

<span lang="en" dir="ltr" class="mw-content-ltr">Instead, if you do that, some applications (for example, steam) won't work.<blockquote>Internals: How it works?</span>

<span lang="en" dir="ltr" class="mw-content-ltr">Flatpak applications run in sandboxes. When you start a flatpak application, flatpak builds a rootfs for it with bubblewrap.</span>

<span lang="en" dir="ltr" class="mw-content-ltr">With <code>findmnt --task {PID of flatpak app}</code> , you can explore the details of its rootfs.</span>

<div lang="en" dir="ltr" class="mw-content-ltr">
By default, flatpak mounts <code>$HOME/.local/share/fonts</code> to <code>/run/host/user-fonts</code> in rootfs of an flatpak application.<syntaxhighlight lang="json">
{
  "target": "/run/host/user-fonts",
  "source": "/dev/disk/by-uuid/b2e1e6b5-738b-410b-b736-6d5c3dbbe31f[/home/username/.local/share/fonts]",
  "fstype": "ext4",
  "options": "ro,nosuid,nodev,relatime"
}
</syntaxhighlight>Then flatpak application can read fonts from that to display contents correctly.</blockquote>
</div>

<span lang="en" dir="ltr" class="mw-content-ltr">==== Solution 2: Symlink to system fonts at  <code>$HOME/.local/share/fonts</code> ====</span>
<span lang="en" dir="ltr" class="mw-content-ltr"><blockquote>'''Note:''' this method doesn't work for some flatpak applications (for example, steam)!</span>

Error: <syntaxhighlight lang="console">
$ flatpak run com.valvesoftware.Steam
bwrap: Can't make symlink at /home/username/.local/share/fonts: File exists
</syntaxhighlight></blockquote>Create a symlink in <code>XDG_DATA_HOME/fonts</code> pointing to <code>/run/current-system/sw/share/X11/fonts</code>, e. g. 
<syntaxhighlight lang="bash">
mkdir $HOME/.local/share/fonts && ln -s /run/current-system/sw/share/X11/fonts ~/.local/share/fonts/
</syntaxhighlight>
<span lang="en" dir="ltr" class="mw-content-ltr">Now you have two options.</span>

<div lang="en" dir="ltr" class="mw-content-ltr">
===== Option 1: Allow access to the fonts folder and <code>/nix/store</code> =====
</div>
<div lang="en" dir="ltr" class="mw-content-ltr">
By using the Flatpak CLI or the Flatseal Flatpak make the following directory available to all Flatpaks <code>$HOME/.local/share/fonts</code> and <code>$HOME/.icons</code> the appropriate commands for this are:
</div>

<syntaxhighlight lang="bash">
flatpak --user override --filesystem=$HOME/.local/share/fonts:ro
flatpak --user override --filesystem=$HOME/.icons:ro
</syntaxhighlight>

<span lang="en" dir="ltr" class="mw-content-ltr">And, because <code>~/.local/share/fonts</code> is linked to <code>/run/current-system/sw/share/X11/fonts</code>, which in turn is linked to content in <code>/nix/store</code>. You need to grant flatpak applications access to the <code>/nix/store</code> directory, so that they can load fonts correctly. You may need to reboot for this to fully take effect.</span>

<syntaxhighlight lang="bash">
flatpak --user override --filesystem=/nix/store:ro
flatpak --user override --filesystem=/run/current-system/sw/share/X11/fonts:ro
</syntaxhighlight>

<span lang="en" dir="ltr" class="mw-content-ltr">===== Option 2: Allow access to the WHOLE filesystem =====</span>
<div lang="en" dir="ltr" class="mw-content-ltr">
Allow them access the WHOLE filesystem of yours: <code>All system files</code> in Flatseal or equivalently <code>filesystem=host</code> available to your application, the command for this is:
</div>

<syntaxhighlight lang="bash">
flatpak --user override --filesystem=host
</syntaxhighlight>

<div lang="en" dir="ltr" class="mw-content-ltr">
It is important to keep in mind that some flatpak apps may refuse to launch if given certain permissions, such as the Steam flatpak.
</div>

<span lang="en" dir="ltr" class="mw-content-ltr">==== Solution 3: Configure bindfs for fonts/cursors/icons support ====</span>
<div lang="en" dir="ltr" class="mw-content-ltr">
Alternatively, you can expose relevant packages directly under <code>/usr/share/...</code> paths. This will also enable Flatpak to use a custom cursor theme if you have one. This solution doesn't require <code>fonts.fontDir.enable</code> to be enabled.<syntaxhighlight lang="nix">
  system.fsPackages = [ pkgs.bindfs ];
  fileSystems = let
    mkRoSymBind = path: {
      device = path;
      fsType = "fuse.bindfs";
      options = [ "ro" "resolve-symlinks" "x-gvfs-hide" ];
    };
    fontsPkgs = config.fonts.packages ++ (with pkgs; [
        # Add your cursor themes and icon packages here
        bibata-cursors
        gnome-themes-extra
        # etc.
      ]);
    x11Fonts = pkgs.runCommand "X11-fonts"
      {
        preferLocalBuild = true;
        nativeBuildInputs = with pkgs; [
          gzip
          mkfontdir
        ];
      }
      (''
        mkdir -p "$out/share/fonts"
        font_regexp='.*\.$ttf\|ttc\|otb\|otf\|pcf\|pfa\|pfb\|bdf$$\.gz$?'
      ''
      + (builtins.concatStringsSep "\n" (builtins.map (pkg: ''
          find ${toString pkg} -regex "$font_regexp" \
            -exec ln -sf -t "$out/share/fonts" '{}' \;
        '') fontsPkgs
        ))
      + ''
        cd "$out/share/fonts"
        mkfontscale
        mkfontdir
        cat $(find ${pkgs.font-alias}/ -name fonts.alias) >fonts.alias
      '');
    aggregatedIcons = pkgs.buildEnv {
      name = "system-icons";
      paths = fontsPkgs;
      pathsToLink = [
        "/share/icons"
      ];
    };
  in {
    "/usr/share/icons" = mkRoSymBind (aggregatedIcons + "/share/icons");
    "/usr/share/fonts" = mkRoSymBind (x11Fonts + "/share/fonts");
  };
</div>

<div lang="en" dir="ltr" class="mw-content-ltr">
fonts.packages = with pkgs; [
    noto-fonts
    noto-fonts-color-emoji
    noto-fonts-cjk-sans
  ];
</syntaxhighlight>Note that font cache inside flatpak container may not be recreated after changes to fonts in <code>/usr/share/fonts</code>, because font cache seem to be relying on file timestamps that are missing in <code>/nix/store</code>.
</div>

<div lang="en" dir="ltr" class="mw-content-ltr">
You can make sure that font directory is bind-mounted properly inside flatpak container by running <code>flatpak enter <instance> findmnt  | grep /run/host/fonts</code>, or by running <code>flatpak enter <instance> ls -alh /run/host/fonts</code> and compare it to <code>ls -alh /usr/share/fonts</code>.
</div>

<div lang="en" dir="ltr" class="mw-content-ltr">
If everything is mounted properly, but you still do not see fonts in flatpak app - force font cache recreation inside flatpak container: <code>flatpak run --command=fc-cache <application id> -f -v</code>
</div>

<span lang="en" dir="ltr" class="mw-content-ltr">=== Noto Color Emoji doesn't render on Firefox ===</span>

<div lang="en" dir="ltr" class="mw-content-ltr">
Enable <code>useEmbeddedBitmaps</code> in your NixOS configuration.
<syntaxhighlight lang="nix">
fonts.fontconfig.useEmbeddedBitmaps = true;
</syntaxhighlight>
</div>
<hr />
[[Category:Configuration]]
[[Category:Desktop]]
[[Category:Fonts]]