🚀 [Feature]: Install only the Nerd Font variants you need with faster reruns (#77)

MariusStorhaug · web-flow · commit fc9eb4091d8c · 2026-05-20T19:24:20.000+02:00
Install-NerdFont can now install only the Nerd Font variants you want, reuse cached archives between runs, and skip work for fonts that are already present in the requested scope. Multi-font installs also finish faster because archive downloads are batched and extraction uses the underlying .NET zip APIs directly. - Fixes #70 - Fixes #71 - Fixes #72 - Fixes #73 - Fixes #74 - Fixes #75 - Fixes #76 ## New: Install only the variants you need Use `-Variant` to limit each archive to the families you actually want to register. This is useful for terminal-focused setups where only the monospace family is needed. ```powershell Install-NerdFont -Name 'FiraCode' -Variant Mono Install-NerdFont -All -Variant Mono ``` `All` remains the default, so existing scripts keep the current behavior unless they opt into `Standard`, `Mono`, or `Propo`. ## Changed: Repeated installs reuse prior work When a font is already installed in the requested scope and `-Force` is not used, `Install-NerdFont` now skips the download, extraction, and install phases for that font. Downloaded archives are cached per Nerd Fonts release, so retries and overlapping reruns can reuse the same zip instead of fetching it again. ```powershell Install-NerdFont -Name 'Hack' Install-NerdFont -Name 'Hack' # skips when already installed Install-NerdFont -Name 'Hack' -Force # re-downloads and reinstalls ``` ## Changed: Multi-font installs complete faster Bulk installs now resolve the target font set once, avoid duplicate work from overlapping name patterns, download archives in bounded batches, and extract them with `System.IO.Compression.ZipFile`. The end result is less waiting during `-All` and other multi-font runs without changing the default install surface. ## Technical Details - `Install-NerdFont` now deduplicates the resolved font list, skips already-installed fonts without `-Force`, caches archives under the user cache directory, downloads uncached archives through `System.Net.Http.HttpClient`, extracts with `System.IO.Compression.ZipFile`, and filters extracted files by `-Variant` before calling `Install-Font`. - `tests/NerdFonts.Tests.ps1` adds coverage for `-Variant Mono` installs. - `scripts/Measure-InstallPerformance.ps1` adds repeatable performance scenarios for single-font, subset, rerun, and optional `-All` measurements. - `README.md` now documents variant installs, skip-on-rerun behavior, and cache bypass with `-Force`. - Implementation plan progress: the work tracked by #70 through #76 is completed in this PR.
diff --git a/README.md b/README.md
@@ -37,6 +37,12 @@ To download the font from the NerdFonts repository and install it on the system,
 Install-NerdFont -Name 'FiraCode' -Scope AllUsers #Tab completion works on Scope too
 ```
 
+To install only a specific variant from the archive, use the `-Variant` parameter. `Mono` is useful for terminal and editor setups where you only want the monospace family.
+
+```powershell
+Install-NerdFont -Name 'FiraCode' -Variant Mono
+```
+
 ### Install all NerdFonts
 
 To install all NerdFonts on the system you can use the following command.
@@ -54,6 +60,12 @@ This requires the shell to run in an elevated context (sudo or run as administra
 Install-NerdFont -All -Scope AllUsers
 ```
 
+You can combine `-All` with `-Variant` to limit what gets installed from each archive:
+
+```powershell
+Install-NerdFont -All -Variant Mono
+```
+
 ### Check if a NerdFont is installed
 
 The [Fonts](https://psmodule.io/Fonts) module is installed automatically as a dependency and provides the
@@ -73,6 +85,23 @@ Get-Font -Name 'FiraCode*' -Scope AllUsers
 
 If the command returns results, the font is installed. If it returns nothing, the font is not installed in that scope.
 
+When you run `Install-NerdFont` again without `-Force`, fonts that are already installed in the requested scope are skipped. Downloaded archives are also cached per Nerd Fonts release so retries and repeated installs do not need to fetch the same ZIP again.
+
+Cache locations:
+
+- Windows: `%LOCALAPPDATA%/PSModule/NerdFonts/cache`
+- macOS and Linux: `$HOME/.cache/PSModule/NerdFonts`
+
+You can inspect the active cache path in PowerShell with:
+
+```powershell
+if ($IsWindows) {
+    Join-Path ([Environment]::GetFolderPath('LocalApplicationData')) 'PSModule/NerdFonts/cache'
+} else {
+    Join-Path $HOME '.cache/PSModule/NerdFonts'
+}
+```
+
 ### Update an installed NerdFont
 
 Individual font files do not embed a NerdFonts release version, so there is no direct way to check whether an installed
@@ -89,7 +118,7 @@ Install-NerdFont -Name 'FiraCode' -Force -Scope AllUsers
 ```
 
 This re-downloads and installs the font version bundled with your installed NerdFonts module, overwriting any existing
-files. To pick up newer font releases, update the NerdFonts module first (`Update-PSResource -Name NerdFonts` if you
+files. `-Force` also bypasses the local archive cache so the font ZIP is fetched again before reinstalling. To pick up newer font releases, update the NerdFonts module first (`Update-PSResource -Name NerdFonts` if you
 installed via PSResourceGet, or `Update-Module -Name NerdFonts` if you installed via PowerShellGet).
 
 ### Uninstall a NerdFont
diff --git a/src/functions/public/Install-NerdFont.ps1 b/src/functions/public/Install-NerdFont.ps1
@@ -29,6 +29,16 @@ function Install-NerdFont {
 
         Installs all Nerd Fonts to the current user.
 
+        .EXAMPLE
+        Install-NerdFont -Name 'FiraCode' -Variant Mono
+
+        Installs only the monospace variant of the font 'FiraCode' to the current user.
+
+        .EXAMPLE
+        Install-NerdFont -All -Variant Mono
+
+        Installs only the monospace variant of all Nerd Fonts to the current user.
+
         .LINK
         https://psmodule.io/NerdFonts/Functions/Install-NerdFont
 
@@ -63,6 +73,11 @@ function Install-NerdFont {
         [ValidateSet('CurrentUser', 'AllUsers')]
         [string] $Scope = 'CurrentUser',
 
+        # Select which variant(s) to install from each archive. Default 'All' preserves current behavior.
+        [Parameter()]
+        [ValidateSet('All', 'Standard', 'Mono', 'Propo')]
+        [string] $Variant = 'All',
+
         # Force will overwrite existing fonts
         [Parameter()]
         [switch] $Force
@@ -76,7 +91,8 @@ Please run the command again with elevated rights (Run as Administrator) or prov
 '@
             throw $errorMessage
         }
-        $nerdFontsToInstall = @()
+        $nerdFontsToInstall = [System.Collections.Generic.List[object]]::new()
+        $seenNames = [System.Collections.Generic.HashSet[string]]::new([System.StringComparer]::OrdinalIgnoreCase)
 
         $guid = (New-Guid).Guid
         $tempPath = Join-Path -Path $HOME -ChildPath "NerdFonts-$guid"
@@ -88,46 +104,243 @@ Please run the command again with elevated rights (Run as Administrator) or prov
 
     process {
         if ($All) {
-            $nerdFontsToInstall = $script:NerdFonts
+            foreach ($font in $script:NerdFonts) {
+                if ($seenNames.Add($font.Name)) { $nerdFontsToInstall.Add($font) }
+            }
         } else {
             foreach ($fontName in $Name) {
-                $nerdFontsToInstall += $script:NerdFonts | Where-Object { $_.Name -like $fontName }
+                foreach ($font in $script:NerdFonts) {
+                    if ($font.Name -like $fontName -and $seenNames.Add($font.Name)) {
+                        $nerdFontsToInstall.Add($font)
+                    }
+                }
             }
         }
+    }
+
+    end {
+        Write-Verbose "[$Scope] - Installing [$($nerdFontsToInstall.Count)] fonts"
 
-        Write-Verbose "[$Scope] - Installing [$($nerdFontsToInstall.count)] fonts"
+        $cacheRoot = if ($IsWindows) {
+            Join-Path -Path ([Environment]::GetFolderPath('LocalApplicationData')) -ChildPath 'PSModule/NerdFonts/cache'
+        } else {
+            Join-Path -Path $HOME -ChildPath '.cache/PSModule/NerdFonts'
+        }
 
+        $installedFamilies = $null
+        if (-not $Force) {
+            $installedNames = @(Get-Font -Scope $Scope -ErrorAction SilentlyContinue | ForEach-Object { $_.Name } | Where-Object { $_ })
+            $installedFamilies = [System.Collections.Generic.HashSet[string]]::new(
+                [string[]]$installedNames,
+                [System.StringComparer]::OrdinalIgnoreCase
+            )
+        }
+
+        $toProcess = [System.Collections.Generic.List[object]]::new()
         foreach ($nerdFont in $nerdFontsToInstall) {
-            $URL = $nerdFont.URL
             $fontName = $nerdFont.Name
-            $downloadFileName = Split-Path -Path $URL -Leaf
-            $downloadPath = Join-Path -Path $tempPath -ChildPath $downloadFileName
+            if (-not $Force -and $installedFamilies) {
+                $alreadyInstalled = $false
+                foreach ($family in $installedFamilies) {
+                    if ($family -like "$fontName Nerd Font*") { $alreadyInstalled = $true; break }
+                }
+                if ($alreadyInstalled) {
+                    Write-Verbose "[$fontName] - already installed, skipping"
+                    continue
+                }
+            }
+            $toProcess.Add($nerdFont)
+        }
 
-            Write-Verbose "[$fontName] - Downloading to [$downloadPath]"
-            if ($PSCmdlet.ShouldProcess("[$fontName] to [$downloadPath]", 'Download')) {
-                Invoke-WebRequest -Uri $URL -OutFile $downloadPath -RetryIntervalSec 5 -MaximumRetryCount 5
+        Add-Type -AssemblyName System.Net.Http -ErrorAction SilentlyContinue
+        $httpClient = [System.Net.Http.HttpClient]::new()
+        # Keep request lifetime unbounded for large archives on slower links.
+        $httpClient.Timeout = [System.Threading.Timeout]::InfiniteTimeSpan
+        $pending = [System.Collections.Generic.List[object]]::new()
+        $readyToInstall = [System.Collections.Generic.List[object]]::new()
+        $downloadErrors = [System.Collections.Generic.List[string]]::new()
+        $throttle = 8
+
+        try {
+            foreach ($nerdFont in $toProcess) {
+                $URL = $nerdFont.URL
+                $fontName = $nerdFont.Name
+                $downloadFileName = Split-Path -Path $URL -Leaf
+                $downloadPath = Join-Path -Path $tempPath -ChildPath $downloadFileName
+
+                $cacheTag = if ($URL -match '/releases/download/([^/]+)/') {
+                    $Matches[1]
+                } else {
+                    'unknown'
+                }
+                $cacheTagDir = Join-Path -Path $cacheRoot -ChildPath $cacheTag
+                $cachedFile = Join-Path -Path $cacheTagDir -ChildPath $downloadFileName
+
+                if ((Test-Path -LiteralPath $cachedFile) -and -not $Force) {
+                    Write-Verbose "[$fontName] - Cache hit at [$cachedFile]"
+                    $cacheHitSuccess = $false
+                    try {
+                        Copy-Item -LiteralPath $cachedFile -Destination $downloadPath -Force -ErrorAction Stop
+                        $cacheHitSuccess = $true
+                    } catch {
+                        Write-Warning "[$fontName] - Cache read failed, falling back to download: $($_.Exception.Message)"
+                    }
+                    if ($cacheHitSuccess) {
+                        $item = [pscustomobject]@{
+                            Name         = $fontName
+                            URL          = $URL
+                            DownloadPath = $downloadPath
+                            CachedFile   = $cachedFile
+                            CacheTagDir  = $cacheTagDir
+                            FromCache    = $true
+                        }
+                        $pending.Add($item)
+                        $readyToInstall.Add($item)
+                    } else {
+                        $item = [pscustomobject]@{
+                            Name         = $fontName
+                            URL          = $URL
+                            DownloadPath = $downloadPath
+                            CachedFile   = $cachedFile
+                            CacheTagDir  = $cacheTagDir
+                            FromCache    = $false
+                        }
+                        $pending.Add($item)
+                    }
+                } else {
+                    Write-Verbose "[$fontName] - Queue download to [$downloadPath]"
+                    $item = [pscustomobject]@{
+                        Name         = $fontName
+                        URL          = $URL
+                        DownloadPath = $downloadPath
+                        CachedFile   = $cachedFile
+                        CacheTagDir  = $cacheTagDir
+                        FromCache    = $false
+                    }
+                    $pending.Add($item)
+                }
             }
 
+            $toDownload = @($pending | Where-Object { -not $_.FromCache })
+            for ($i = 0; $i -lt $toDownload.Count; $i += $throttle) {
+                $end = [Math]::Min($i + $throttle - 1, $toDownload.Count - 1)
+                $chunk = $toDownload[$i..$end]
+                $tasks = @()
+                foreach ($q in $chunk) {
+                    $tasks += [pscustomobject]@{ Q = $q; Task = $httpClient.GetByteArrayAsync($q.URL) }
+                }
+                foreach ($t in $tasks) {
+                    try {
+                        $bytes = $t.Task.GetAwaiter().GetResult()
+                        [System.IO.File]::WriteAllBytes($t.Q.DownloadPath, $bytes)
+                        $readyToInstall.Add($t.Q)
+                    } catch {
+                        $downloadErrors.Add("[$($t.Q.Name)] - Download failed: $($_.Exception.Message)")
+                    }
+                }
+            }
+        } finally {
+            $httpClient.Dispose()
+        }
+
+        foreach ($p in $readyToInstall) {
+            $fontName = $p.Name
+            $downloadPath = $p.DownloadPath
             $extractPath = Join-Path -Path $tempPath -ChildPath $fontName
             Write-Verbose "[$fontName] - Extract to [$extractPath]"
             if ($PSCmdlet.ShouldProcess("[$fontName] to [$extractPath]", 'Extract')) {
-                Expand-Archive -Path $downloadPath -DestinationPath $extractPath -Force
-                Remove-Item -Path $downloadPath -Force
+                if (-not (Test-Path -LiteralPath $extractPath)) {
+                    $null = New-Item -ItemType Directory -Path $extractPath
+                }
+                [System.IO.Compression.ZipFile]::ExtractToDirectory($downloadPath, $extractPath, $true)
+
+                if (-not $p.FromCache -and (Test-Path -LiteralPath $downloadPath)) {
+                    $tempCachePath = $null
+                    try {
+                        if (-not (Test-Path -LiteralPath $p.CacheTagDir)) {
+                            $null = New-Item -ItemType Directory -Path $p.CacheTagDir -Force -ErrorAction Stop
+                        }
+                        $tempCachePath = "$($p.CachedFile).$PID.tmp"
+                        Copy-Item -LiteralPath $downloadPath -Destination $tempCachePath -Force -ErrorAction Stop
+                        Move-Item -LiteralPath $tempCachePath -Destination $p.CachedFile -Force -ErrorAction Stop
+                    } catch {
+                        Write-Warning "[$fontName] - Download succeeded but cache write failed: $($_.Exception.Message)"
+                        if ($tempCachePath -and (Test-Path -LiteralPath $tempCachePath)) {
+                            Remove-Item -LiteralPath $tempCachePath -Force -ErrorAction SilentlyContinue
+                        }
+                    }
+                }
+
+                Remove-Item -LiteralPath $downloadPath -Force -ErrorAction SilentlyContinue
+            }
+
+            if ($Variant -ne 'All') {
+                $allFiles = Get-ChildItem -Path $extractPath -Recurse -File -Include '*.ttf', '*.otf'
+                $keep = switch ($Variant) {
+                    'Mono' {
+                        $allFiles | Where-Object { $_.Name -like '*NerdFontMono*' }
+                    }
+                    'Propo' {
+                        $allFiles | Where-Object { $_.Name -like '*NerdFontPropo*' }
+                    }
+                    'Standard' {
+                        $allFiles | Where-Object {
+                            $_.Name -like '*NerdFont*' -and
+                            $_.Name -notlike '*NerdFontMono*' -and
+                            $_.Name -notlike '*NerdFontPropo*'
+                        }
+                    }
+                }
+                $keepNames = [string[]]@($keep.FullName)
+                $keepSet = [System.Collections.Generic.HashSet[string]]::new(
+                    $keepNames,
+                    [System.StringComparer]::OrdinalIgnoreCase
+                )
+                $removed = 0
+                foreach ($f in $allFiles) {
+                    if (-not $keepSet.Contains($f.FullName)) {
+                        Remove-Item -LiteralPath $f.FullName -Force -ErrorAction SilentlyContinue
+                        $removed++
+                    }
+                }
+                Write-Verbose "[$fontName] - Variant '$Variant': kept $($keep.Count), removed $removed"
+            }
+
+            # Nerd Fonts archives sometimes contain duplicate matching files in
+            # compatibility subfolders. Keep a single file per filename.
+            $remaining = @(Get-ChildItem -Path $extractPath -Recurse -File -Include '*.ttf', '*.otf')
+            $preferred = $remaining | Sort-Object -Property @(
+                @{ Expression = { if ($_.FullName -match '(?i)[\\/]Windows Compatible[\\/]') { 1 } else { 0 } } }
+                @{ Expression = { $_.FullName.Length } }
+            )
+            $seenFileNames = [System.Collections.Generic.HashSet[string]]::new([System.StringComparer]::OrdinalIgnoreCase)
+            $duplicateRemoved = 0
+            foreach ($file in $preferred) {
+                if ($seenFileNames.Add($file.Name)) { continue }
+                Remove-Item -LiteralPath $file.FullName -Force -ErrorAction SilentlyContinue
+                $duplicateRemoved++
+            }
+            if ($duplicateRemoved -gt 0) {
+                Write-Verbose "[$fontName] - Deduplicated $duplicateRemoved file(s)"
             }
 
             Write-Verbose "[$fontName] - Install to [$Scope]"
             if ($PSCmdlet.ShouldProcess("[$fontName] to [$Scope]", 'Install font')) {
                 Install-Font -Path $extractPath -Scope $Scope -Force:$Force
-                Remove-Item -Path $extractPath -Force -Recurse
+                Remove-Item -LiteralPath $extractPath -Force -Recurse -ErrorAction SilentlyContinue
             }
         }
-    }
 
-    end {
+        foreach ($err in $downloadErrors) {
+            Write-Error $err
+        }
+
         Write-Verbose "Remove folder [$tempPath]"
     }
 
     clean {
-        Remove-Item -Path $tempPath -Force
+        if ($tempPath -and (Test-Path -LiteralPath $tempPath)) {
+            Remove-Item -LiteralPath $tempPath -Force -Recurse -ErrorAction SilentlyContinue
+        }
     }
 }
diff --git a/tests/NerdFonts.Tests.ps1 b/tests/NerdFonts.Tests.ps1
