Fonts/zh-cn: Difference between revisions

Revision as of 12:48, 9 July 2026

NixOS 处理字体就像处理系统中许多不同部分一样：除非明确标记为环境的一部分，否则它们不会出现在环境中。本指南涵盖字体的安装、配置和故障排除。

在 NixOS 上安装字体

NixOS 有许多可用的字体包，你可以轻松地在这里搜索并使用他们： NixOS packages site.

尽管这些字体包看起来与普通包无异，但仅将它们添加到 `environment.systemPackages` 并不会让应用程序能够访问这些字体。要实现这一点，应将它们放入 NixOS 的 `fonts.packages` 选项列表中。

For example:

❄︎ /etc/nixos/configuration.nix

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
];

Note: Be aware that sometimes font names and packages name differ and there is no universal convention in NixOS.
See: Guidelines for font packaging

=== Shorthands for fonts ===

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

=== Using fonts from TexLive ===

You can make use of all TeX/LaTeX fonts from CTAN and TexLive by passing the fonts attribute of your TexLive package to fonts.package:

❄︎ /etc/nixos/configuration.nix

{ 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 ];
}

=== Installing nerdfonts ===

Individual Nerd Fonts can be installed like so:

❄︎ /etc/nixos/configuration.nix

fonts.packages = with pkgs; [
  nerd-fonts.fira-code
  nerd-fonts.droid-sans-mono
];

The available Nerd Font subpackages can be listed by searching for nerd-fonts.* on the NixOS Package Search or by running the following command:

$ nix-instantiate --eval --expr "with (import <nixpkgs> {}); lib.attrNames (lib.filterAttrs (_: lib.isDerivation) nerd-fonts)"

Installing all `nerdfonts`

Installing all fonts from the 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 nerd-font attribute:

❄︎ /etc/nixos/configuration.nix

{ 
  fonts.packages = builtins.filter lib.attrsets.isDerivation (builtins.attrValues pkgs.nerd-fonts);
}
&lt;/div&gt;

&lt;div lang="en" dir="ltr" class="mw-content-ltr"&gt;
# or if you already have fonts.packages set
&lt;/div&gt;

&lt;div lang="en" dir="ltr" class="mw-content-ltr"&gt;
{
  fonts.packages = [
     # ... some fonts
  ] 
  ++ builtins.filter lib.attrsets.isDerivation (builtins.attrValues pkgs.nerd-fonts);
}

=== Patching nerdfonts into fonts ===

Not all fonts have Nerd Fonts variants, thankfully you can easily patch them in yourself.

❄︎ /etc/nixos/configuration.nix

(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
  '';
}))

=== Let Fontconfig know the fonts within your Nix profile ===

Nix inserts its user profile path into $XDG_DATA_DIRS, which Fontconfig by default doesn't look in. This cause graphical applications like KDE Plasma not able to recognize the fonts installed via nix-env or nix profile.

To solve this, add the file 100-nix.conf to your Fontconfig user configuration directory (usually $XDG_CONFIG_HOME/fontconfig/conf.d):

<?xml version="1.0"?>
<!DOCTYPE fontconfig SYSTEM "urn:fontconfig:fonts.dtd">
<fontconfig>
  <!-- NIX_PROFILE is the path to your Nix profile. See Nix Reference Manual for details. -->
  <dir>NIX_PROFILE/lib/X11/fonts</dir>
  <dir>NIX_PROFILE/share/fonts</dir>
</fontconfig>

and run fc-cache.

Alternatively, enable Fontconfig configuration in your Home Manager configuration.

=== Imperative installation of user fonts === This is useful for quick font experiments.

Example: Install SourceCodePro-Regular.

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

=== Install fonts in nix-shells ===

fonts is not available as set-valued option in mkshell (gives you an error because it tries to coerce an attribute set into a string). Instead, insert the following:

^[1]

{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}"
    '';
  }

Then typst fonts finds the installed fonts in the nix-shell.

== Configuring fonts ==

The nixos key fonts.fontconfig (click to see the full list!) handles the fontconfig options. Some options are nicely wrapped in nix; there's always localConf to go straight to the XML.

=== Set multiple fonts for different languages ===

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

Vazirmatn font for Persian texts, but Ubuntu

and Liberation Serif fonts for English texts. Just put these lines into your configuration.nix:

❄︎ /etc/nixos/configuration.nix

#----=[ 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" ];
    };
  };
};

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.
defaultFonts translates to <prefer> 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 serif is not a good visual match. You might need not one, but two (or if you count monospace, three!) font packages for a language.

=== Use custom font substitutions ===

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". fc-match NewCenturySchlbk would display similiar info.

Adding this to your /etc/nixos/configuration.nix should prompt it to use the more similar (and nicer) serif Schola font instead:

❄︎ /etc/nixos/configuration.nix

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>
    '';
  };
};

For more information and examples on the xml configuration language:

For a list of suitable replacement fonts:

https://wiki.archlinux.org/title/Metric-compatible_fonts

== Troubleshooting ==

=== What font names can be used in fonts.fontconfig.defaultFonts.monospace? ===

Those that fontconfig will understand. This can be queried from a font file using fc-query.

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

Note that you may need to set fonts.fontDir.enable = true; for that X11/fonts directory to exist.

=== Adding personal fonts to ~/.fonts doesn't work ===

The ~/.fonts directory is being deprecated upstream^[2]. It already doesn't work in NixOS.

The new preferred location is in $XDG_DATA_HOME/fonts, which for most users will resolve to ~/.local/share/fonts

^[3]

=== Flatpak applications can't find system fonts ===

To expose available fonts under /run/current-system/sw/share/X11/fonts, enable fontDir in your NixOS configuration.

❄︎ /etc/nixos/configuration.nix

fonts.fontDir.enable = true;

You will then need to link/copy this folder to one of the Flatpak-supported locations - see below.

==== Solution 1: Copy fonts to $HOME/.local/share/fonts ====

Create fonts directory $HOME/.local/share/fonts and copy system fonts with option -L, --dereference. You will need to repeat this step whenever the fonts change.

$ mkdir $HOME/.local/share/fonts && cp -L /run/current-system/sw/share/X11/fonts/* $HOME/.local/share/fonts/

Note: There is no need to grant flatpak applications access to $HOME/.local/share/fonts.

Instead, if you do that, some applications (for example, steam) won't work.

Internals: How it works?
Flatpak applications run in sandboxes. When you start a flatpak application, flatpak builds a rootfs for it with bubblewrap.
With findmnt --task {PID of flatpak app} , you can explore the details of its rootfs.
By default, flatpak mounts $HOME/.local/share/fonts to /run/host/user-fonts in rootfs of an flatpak application.
{
  "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"
}
Then flatpak application can read fonts from that to display contents correctly.

==== Solution 2: Symlink to system fonts at $HOME/.local/share/fonts ====

Note: this method doesn't work for some flatpak applications (for example, steam)! Error:
$ flatpak run com.valvesoftware.Steam
bwrap: Can't make symlink at /home/username/.local/share/fonts: File exists

Create a symlink in XDG_DATA_HOME/fonts pointing to /run/current-system/sw/share/X11/fonts, e. g.

mkdir $HOME/.local/share/fonts && ln -s /run/current-system/sw/share/X11/fonts ~/.local/share/fonts/

Now you have two options.

Option 1: Allow access to the fonts folder and `/nix/store`

By using the Flatpak CLI or the Flatseal Flatpak make the following directory available to all Flatpaks $HOME/.local/share/fonts and $HOME/.icons the appropriate commands for this are:

flatpak --user override --filesystem=$HOME/.local/share/fonts:ro
flatpak --user override --filesystem=$HOME/.icons:ro

And, because ~/.local/share/fonts is linked to /run/current-system/sw/share/X11/fonts, which in turn is linked to content in /nix/store. You need to grant flatpak applications access to the /nix/store directory, so that they can load fonts correctly. You may need to reboot for this to fully take effect.

flatpak --user override --filesystem=/nix/store:ro
flatpak --user override --filesystem=/run/current-system/sw/share/X11/fonts:ro

===== Option 2: Allow access to the WHOLE filesystem =====

Allow them access the WHOLE filesystem of yours: All system files in Flatseal or equivalently filesystem=host available to your application, the command for this is:

flatpak --user override --filesystem=host

It is important to keep in mind that some flatpak apps may refuse to launch if given certain permissions, such as the Steam flatpak.

==== Solution 3: Configure bindfs for fonts/cursors/icons support ====

Alternatively, you can expose relevant packages directly under /usr/share/... paths. This will also enable Flatpak to use a custom cursor theme if you have one. This solution doesn't require fonts.fontDir.enable to be enabled.

  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
  ];

Note that font cache inside flatpak container may not be recreated after changes to fonts in /usr/share/fonts, because font cache seem to be relying on file timestamps that are missing in /nix/store.

You can make sure that font directory is bind-mounted properly inside flatpak container by running flatpak enter <instance> findmnt | grep /run/host/fonts, or by running flatpak enter <instance> ls -alh /run/host/fonts and compare it to ls -alh /usr/share/fonts.

If everything is mounted properly, but you still do not see fonts in flatpak app - force font cache recreation inside flatpak container: flatpak run --command=fc-cache <application id> -f -v

=== Noto Color Emoji doesn't render on Firefox ===

Enable useEmbeddedBitmaps in your NixOS configuration.

fonts.fontconfig.useEmbeddedBitmaps = true;

[1] ttps://programming.dev/post/32484220

[2] ttps://lists.freedesktop.org/archives/fontconfig/2014-July/005269.html

[3] ttps://lists.freedesktop.org/archives/fontconfig/2014-July/005270.html

[1]

[2]

[3]

Revision as of 12:48, 9 July 2026

Installing all nerdfonts

Option 1: Allow access to the fonts folder and /nix/store

Installing all `nerdfonts`

Option 1: Allow access to the fonts folder and `/nix/store`