# Install Windows or macOS fonts on Linux

> Install and switch between Windows or macOS fonts on Linux, and restore system fonts.

Source: https://console.getchrovia.com/en/docs/sdk-linux-fonts

This guide is for Ubuntu / Debian headless crawling servers. Install the font library matching the browser's target platform. Install both libraries if you need to switch between them.

Run the commands as the crawler's user. For Docker deployments, run them inside the browser's container. This guide uses system-wide font settings, not per-browser-instance settings.

| Target platform | Download | Size |
| --- | --- | --- |
| Windows | [windows-fonts.zip](https://console.getchrovia.com/api/assets/fonts/windows-fonts.zip) | About 204 MB |
| macOS | [macos-fonts.tar.gz](https://console.getchrovia.com/api/assets/fonts/macos-fonts.tar.gz) | About 513 MB |

## 1. Prepare the environment

```sh
sudo apt-get update
sudo apt-get install -y ca-certificates curl fontconfig unzip tar gzip
mkdir -p "$HOME/.cache/chrovia-font-downloads"
cd "$HOME/.cache/chrovia-font-downloads"
```

## 2. Download and extract

Stop the browser, then run the commands for the platform you need. To install both libraries, complete both the Windows and macOS sections.

### Windows

```sh
curl -fL --retry 3 --connect-timeout 15 \
  https://console.getchrovia.com/api/assets/fonts/windows-fonts.zip \
  -o windows-fonts.zip &&
printf '%s  %s\n' \
  f73fafa0081a1ba0714531f7a4d45d4fa47e6fbfa1753a6bd5a030d5f0519fc7 \
  windows-fonts.zip | sha256sum -c - &&
sudo mkdir -p /opt/windows-fonts &&
sudo unzip -o windows-fonts.zip -d /opt/windows-fonts
```

After extraction, set the font read permissions:

```sh
sudo chmod -R a+rX /opt/windows-fonts
```

### macOS

```sh
curl -fL --retry 3 --connect-timeout 15 \
  https://console.getchrovia.com/api/assets/fonts/macos-fonts.tar.gz \
  -o macos-fonts.tar.gz &&
printf '%s  %s\n' \
  f2e48e5bc9cee81a96adae994a2695d3cfe5ce5dc63dccd5642c61da96397c89 \
  macos-fonts.tar.gz | sha256sum -c - &&
sudo mkdir -p /opt/macos-fonts &&
sudo tar --no-same-owner -xzf macos-fonts.tar.gz -C /opt/macos-fonts &&
sudo chmod -R a+rX /opt/macos-fonts
```

## 3. Select a font library

Run the following commands to enable Windows fonts. To enable macOS fonts, replace `/opt/windows-fonts` with `/opt/macos-fonts` in the XML.

```sh
sudo rm -f /etc/fonts/conf.d/99-windows-fonts.conf \
  /etc/fonts/conf.d/99-macos-fonts.conf
sudo tee /etc/fonts/conf.d/99-chrovia-fonts.conf >/dev/null <<'EOF'
<?xml version="1.0"?>
<!DOCTYPE fontconfig SYSTEM "urn:fontconfig:fonts.dtd">
<fontconfig>
  <reset-dirs />
  <dir>/opt/windows-fonts</dir>
</fontconfig>
EOF
```

## 4. Refresh the cache and verify

Remove any `FONTCONFIG_FILE` or `FONTCONFIG_PATH` settings from the browser launcher or service, then run:

```sh
unset FONTCONFIG_FILE FONTCONFIG_PATH
fc-cache -f
fc-list --format='%{file}\n' | sort -u
```

Confirm that the list is not empty and all font paths are under the selected `/opt/windows-fonts/` or `/opt/macos-fonts/` directory.

Check font matching. For macOS, replace `Arial` with `Helvetica`:

```sh
fc-match -f '%{family}: %{file}\n' 'Arial'
```

Confirm that the returned font family and file path match the selected library, then fully quit and restart the browser or crawler service.

## Switch font libraries

Once both libraries are installed and configured as above, stop the browser, then run the commands for the target platform.

Switch to Windows:

```sh
sudo sed -i 's|/opt/macos-fonts|/opt/windows-fonts|' /etc/fonts/conf.d/99-chrovia-fonts.conf &&
fc-cache -f
```

Switch to macOS:

```sh
sudo sed -i 's|/opt/windows-fonts|/opt/macos-fonts|' /etc/fonts/conf.d/99-chrovia-fonts.conf &&
fc-cache -f
```

Repeat the font path and matching checks in step 4, then start the browser.

## Restore system fonts

Run the following commands to restore system fonts:

```sh
sudo rm -f /etc/fonts/conf.d/99-chrovia-fonts.conf &&
fc-cache -f
```

Then fully quit and restart the browser or crawler service.

Open **Computed → Rendered Fonts** in DevTools to check which fonts a page uses. See [Extended Preferences](https://console.getchrovia.com/en/docs/sdk-extended-preferences) for browser configuration.