Guide · fixes

Fastfetch troubleshooting

Paste your error message into search (/) or scan the list below. Error texts are copied from the 2.71.0 source, so they match what your terminal prints.

Checked against v2.71.0Updated 2026-11-06
First, two commandsfastfetch --version tells you which release you have (many distributions ship old ones), and fastfetch --show-errors prints why a module or logo failed instead of silently skipping it.

"fastfetch: command not found"#

  • Right after apt install fastfetch printed E: Unable to locate package fastfetch: the install never happened. Ubuntu 22.04 and 24.04, Linux Mint 21 and 22, and Debian 12 don't have fastfetch in their repositories; we reproduced this in clean containers. Use the PPA or the .deb (Ubuntu, Debian & Mint guide).
  • Installed, but the shell can't find it: open a new terminal, or run hash -r. On Windows, winget says Path environment variable modified; restart your shell, so open a new PowerShell window.
  • Every new terminal prints it: you uninstalled fastfetch but your shell's startup file still runs it. Remove the line (where to look).

More cases, including Homebrew on Linux and unpacked binaries, are on the install page.

fastfetch prints nothing or stops with an error#

  1. Check the exit code: fastfetch; echo $?. Anything but 0 means it stopped early, and the reason is on stderr.
  2. Run once without your config: fastfetch -c none. If that works, the problem is in your config file. A config error stops fastfetch with a message such as JsonConfig Error (display.foo): Unknown display property. With --format json the error still goes to stderr and nothing is printed on stdout, which looks like "no output" in scripts (exit 221 on Linux and macOS, 477 on Windows, in our tests).
  3. If it says unknown option, the command came from a guide for a different version (below).

Config changes aren't showing up#

  • Wrong file name. fastfetch only loads config.jsonc or config.json5 automatically. A file named config.json is ignored (that's in the source: those are the only two names it tries).
  • Wrong folder. Run fastfetch --list-config-paths; the folder holding the config it loads is marked (*). The first match wins, so an older file earlier in the list hides yours.
  • Something passes -c. On Bazzite, fastfetch is an alias that loads Bazzite's own config (fix). Check your own aliases with type fastfetch.
  • A key is misspelled inside a module. Unknown keys inside a module are ignored silently. Run fastfetch --show-errors to see Unknown JSON key messages, and add the $schema line so your editor catches them.

The logo isn't changing#

  • A typo in the logo name silently falls back to your distribution's logo. With --show-errors, -l not-a-real-logo printed Logo: Failed to resolve logo source: not-a-real-logo in our test. Names are case-insensitive; fastfetch --list-logos lists them all.
  • An image file that isn't found gives the same message. Relative paths are resolved from the current directory, not the config file's folder (tested).
  • An old cached image: after changing the logo type for the same picture, run once with --logo-cache regen.
  • Your config isn't loaded at all: see above.

"JsonConfig Error" after an upgrade#

Recent releases renamed or removed options. Errors in the logo, general or display sections stop fastfetch; module-level notices only appear with --show-errors. Find your message below:

ReleaseMessage you seeFixTested
2.71.0Separator: Property 'string' must not be empty (only with --show-errors; otherwise the default - is used)Remove "string": "" from the separator module, or give it at least one character. To hide the line, remove the module. Before 2.71.0 the same config made fastfetch hang.✓
before 2.71.0Error: unknown --logo-type value: spin or JsonConfig Error (logo.type): Invalid enum stringThe spin logo needs 2.71.0 or newer. Check fastfetch --version.✓
2.70.0useStdErr is deprecated, use useOutput insteadIn Command modules, replace "useStdErr": true with "useOutput": "stderr" (or "stdout"; the default is "both").✓
2.70.0A qjs:… format prints as raw textQuickJS scripting was removed. Rewrite the script in Lua (lua:).–
2.70.0{size-available} prints literally in DiskUse {size-free}, which now follows "useAvailable".–
2.70.0-l postmarketos shows your normal logoThe logo was renamed: use -l nura.✓
2.69.0JsonConfig Error (logo.recache): Property 'logo.recache' has been replaced by 'logo.cache' with the value "regen"Delete "recache" from logo. Use "cache": "regen" to force regeneration, or true/false.✓
2.69.0--logo-recache has been replaced by --logo-cache regenUse --logo-cache regen.✓
2.67.0Error: unknown option: --gen-config-forceRemoved, along with --gen-config-full. Run fastfetch --gen-config; the interactive setup asks before overwriting, and its o key switches to a full config.✓
2.67.0JsonConfig Error (general.preRun): general.preRun is removed due to security concerns.Remove preRun from general.✓
2.63.0JsonConfig Error (general.wmiTimeout): Unknown general propertyRemove wmiTimeout (Windows); it no longer exists.–
2.58.0Key `slowVersionDetection` is deprecated, it's always trueRemove it from the DE module.–
2.53.0The option length has been renamed to times.In Separator modules, rename "length" to "times".–
2.52.0+Error: Unsupported module option: --cpu-tempPer-module flags were removed in 2.50.0. Put the option in the config, e.g. {"type": "cpu", "temp": true}. The error message prints the exact JSON to use.✓
2.50.0JsonConfig Error (display.bar): display.bar.charElapsed has been renamed to display.bar.char.elapsed.Same pattern for charTotal → char.total, borderLeft → border.left, borderRight → border.right.✓
2.50.0Error: unknown option: --load-configUse -c / --config.✓
2.50.0JsonConfig Error (display.Separator): Unknown display propertyKeys are case-sensitive since 2.50.0: write separator.✓

✓ means we reproduced the exact message by running fastfetch (2.70.0, or 2.71.0 for the 2.71.0 rows) on Linux, macOS and Windows (see the lab results). – means it is taken from the source code only.

Other messages you may meet:

  • Error: failed to parse JSON config file `…` at (row, col): …: a syntax error (missing comma or quote) at that line and column.
  • Error: couldn't find config: …: the name passed to -c doesn't exist. Presets are listed by fastfetch --list-presets.
  • module object must contain a "type" key ( case sensitive ): a module object without "type".
  • Error: module `command` is not supported with `--structure`: Command modules can't be selected with -s; put them in the config.

No colors, or black-and-white output#

Fastfetch turns colors off when its output isn't a terminal (piped, redirected) or when the NO_COLOR environment variable is set. The ASCII logo still prints, without colors; image logos are skipped.

  • Powerlevel10k: its instant prompt captures everything printed after it starts, so the output "may appear uncolored" (Powerlevel10k's docs). Move fastfetch above the instant-prompt block in ~/.zshrc (example).
  • Force colors: fastfetch --pipe false.
  • Check for NO_COLOR: echo $NO_COLOR (any value disables colors).

Adding fastfetch to .bashrc broke scp, sftp or rsync#

Non-interactive SSH sessions also read ~/.bashrc on Ubuntu and Debian, and any output there corrupts file transfers. In our test, a bare fastfetch at the top of ~/.bashrc made scp fail with scp: Ensure the remote shell produces no output for non-interactive sessions. and rsync with protocol incompatibility (code 2). Only run fastfetch in interactive shells (full test):

~/.bashrc
[[ $- == *i* ]] && fastfetch

fastfetch replaces an image it can't draw with your distribution's ASCII logo, silently unless you add --show-errors. These are the messages we saw in our tests, with what each means:

MessageFix
Logo: Failed to resolve logo source: …The file wasn't found, or the logo name is misspelled. Use ~/ or an absolute path.
Logo: Failed to load / convert the image sourceThe image library is missing: install libchafa for chafa, or ImageMagick for kitty/sixel on Linux.
Logo: getCharacterPixelDimensions() failedThe output isn't a terminal, or the terminal doesn't report its size. Run fastfetch directly in the terminal.
Logo: Image logo is not supported in pipe modeOutput is piped or NO_COLOR is set (message from the source code).
Logo: the image source can not be animated by this buildGIF playback needs ImageMagick 7 on Linux; drop --logo-animation-frame 0.

Also make sure the logo type suits your terminal: kitty for kitty, Ghostty and WezTerm; iterm for iTerm2; sixel for Windows Terminal; chafa for everything else. The image logo guide covers every case, with screenshots.

Icons show as boxes or question marks#

You're using icon keys (display.key.type set to icon or both) or keyIcon without a Nerd Font in your terminal. Install a font from nerdfonts.com and select it in your terminal settings, or switch back to text keys ("type": "string").

GPU shows as "Device XXXX" or a generic name#

Your PCI ID database is older than your GPU. The README's fix: download pci.ids and overwrite /usr/share/hwdata/pci.ids. For AMD, also update /usr/share/libdrm/amdgpu.ids from Mesa. Or ask the driver directly:

config.jsonc
{ "type": "gpu", "driverSpecific": true }

The README still shows the old --gpu-driver-specific flag; that stopped working in 2.50.0.

On Linux with an AMD GPU whose PCI device or revision ID starts with zeros, versions before 2.71.0 could miss the name in an up-to-date amdgpu.ids; 2.71.0 fixes that lookup.

CPU or GPU temperature is missing#

Temperature is off by default. Enable it per module with {"type": "cpu", "temp": true} (same for gpu and battery). If it still doesn't appear, your system doesn't expose a sensor fastfetch can read; --show-errors says which.

Package count is lower than Neofetch's#

The README explains that Neofetch over-counted: on Debian-based systems it included removed packages that still have config files (rc state), and on RPM systems it counted gpg-pubkey entries. On Windows, winget packages are not counted by default; {"type": "packages", "disabled": []} enables every package manager.

Shell shows mise or atuin instead of your shell#

Before 2.71.0, the Shell module could report a tool that sits between the terminal and your shell, such as the mise version manager or atuin shell history, as the shell itself (#2686). 2.71.0 skips both. On an older version, update, or use a "format" on the shell module that prints the shell you want.

Memory usage differs from other tools#

Tools define "used" memory differently; the project discusses this in issue #1096. Since 2.65.2, ZFS ARC cache is not counted as used.

Fastfetch feels slow#

Measure first: fastfetch --stat appends each module's time in milliseconds (and also turns on error output). Usual suspects:

ModuleWhy it takes timeWhat to do
CPUUsageSamples twice, waitTime apart (default 200 ms)Remove it, or lower waitTime
NetIO, DiskIO, TopSample twice (default 250 ms)Remove, or lower waitTime
PublicIp, WeatherNetwork requestsRemove, or set a shorter timeout
TerminalThemeWaits up to 1 s for the terminal to answerRemove it if your terminal doesn't answer color queries
PackagesCounts many package databasesUse "disabled" to skip managers you don't use
OpenGL, VulkanInitialize a graphics APIRemove if you don't need them

Total run time of the ci.jsonc preset on upstream CI

Wall-clock time per runner, latest CI run (2026-11-02). Hover a bar for how much is deliberate waiting.

Source: fastfetch CI benchmark
View the data as a table
RunnerTotal process time, ci.jsonc preset
Linux x86-64290 ms
Linux ARM64270 ms
macOS ARM64800 ms
Windows x86-642590 ms
Windows ARM642490 ms

The Windows totals are high because CI runners have no real terminal, so terminal queries wait their full timeout. That is not typical of a desktop.

It never finishes at all? On 2.70.0 and older, check your config for a separator module with "string": "": in our test that made 2.70.0 hang on Linux, macOS and Windows, and 2.71.0 rejects it instead. Before 2.71.0, fastfetch could also wait forever when the terminal answered a query only partly, for example with only one of the two OSC 10/11 color replies. The changelog lists the logo, Terminal and TerminalTheme code as affected, on Unix and Windows. Update to 2.71.0; on an older version, removing terminaltheme from your modules is the first thing to try.

"Authorization required, but no authorization protocol specified" as root#

The README's fix: export XAUTHORITY=$HOME/.Xauthority before running fastfetch with root privileges.

A command from a guide fails with "unknown option"#

Either the guide is older than your fastfetch (flags like --cpu-format were removed in 2.50.0), or your fastfetch is older than the guide. Debian 13, for example, ships 2.40.4, which lacks --structure-disabled, the interactive --gen-config and --logo-cache. Compare fastfetch --version with the release history, and see which version each distribution ships.

Exit codes in scripts#

Fastfetch exits 0 on success. Its error codes are larger than 255, so POSIX shells see them modulo 256 while Windows shows the full number. Test for "non-zero" rather than a specific value:

SituationLinux/macOS shellWindows
Unknown option144400
Config not found (-c)158414
Config error, or non-interactive --gen-config target exists221477

A module that detects nothing does not change the exit code. ✓ tested Every value in this table was measured on Ubuntu, macOS and Windows Server runners.

Still stuck?#

Usage questions go to GitHub Discussions, bugs to the issue tracker. Include the output of fastfetch --version and fastfetch --show-errors. If something on this page is wrong, email hello@fastfetch.dev.