Guide · Logos

Image, GIF and animated logos in fastfetch

fastfetch can draw a real picture where the ASCII logo goes, and on the right build it can even play a GIF. Whether it works depends on three things: your terminal, the logo type, and a library your fastfetch build loads at run time. We tested all three in kitty on Ubuntu and Arch on 2026-11-02, including every error message below.

Checked against v2.71.0Updated 2026-11-06

Show an image: the short version#

bash
fastfetch --logo ~/Pictures/me.png --logo-width 30

In kitty this worked as-is. fastfetch saw it was running in kitty and used the kitty graphics protocol:

$ fastfetch --logo landscape.png --logo-width 30
Screenshot: output of fastfetch --logo landscape.png --logo-width 30
Picked automatically in kitty · Real screenshot from our lab, Ubuntu 24.04, kitty 0.32.2
$ fastfetch --logo landscape.png --logo-type chafa --logo-width 30
Screenshot: output of fastfetch --logo landscape.png --logo-type chafa --logo-width 30
--logo-type chafa: the same image as colored text · Real screenshot from our lab, Ubuntu 24.04, kitty 0.32.2, libchafa 1.14

In other terminals, name the logo type yourself. The fastfetch wiki recommends that anyway: it calls the automatic choice "known to be buggy for some terminals". The rest of this page explains which type to use and what to do when the image doesn't appear.

Which logo type for your terminal#

TerminalUseWhat auto picks
kitty--logo-type kitty (also plays GIFs)kitty protocol ✓ tested
Ghostty, WezTerm, Konsole, Warp--logo-type kittykitty protocol
iTerm2--logo-type itermiTerm protocol
Windows Terminal--logo-type sixel ✓ testedchafa
Apple's Terminal (macOS)No good option: chafa came out unrecognizable in our test. Use iTerm2, kitty, Ghostty or WezTerm for imageschafa ✓ tested
Anything else: GNOME Terminal, Alacritty, the Linux console…--logo-type chafachafa ✓ tested

The third column comes from fastfetch's source (src/logo/logo.c, the same in 2.70.0 and 2.71.0):

  • When the logo is a file that doesn't end in .txt, auto uses the iTerm protocol in iTerm2.
  • It uses the kitty protocol when the terminal process is kitty, Konsole, WezTerm, wayst, Ghostty or Warp.
  • Everywhere else it uses chafa. It never picks sixel on its own.

Want movement without an image? Since 2.71.0 the spin logo type turns your ASCII logo as a 3D slab in any terminal, no image protocol needed: fastfetch --logo-type spin --watch 1 (options).

We tested kitty, Windows Terminal and Apple's Terminal ourselves; the other rows reflect the source code and the official logo documentation. The 2.69.0 changelog says Windows Terminal shows sixel logos "out of the box", and it did. With Scoop's fastfetch 2.70.0 in Windows Terminal 1.23 the image appeared with nothing else installed:

$ fastfetch --logo landscape.png --logo-type sixel --logo-width 30
Screenshot: output of fastfetch --logo landscape.png --logo-type sixel --logo-width 30
Windows Terminal 1.23: a sixel image logo, no extra software needed · Real screenshot from our lab, Windows Server 2025

Apple's Terminal is the opposite case. It has no image protocol, so auto falls back to chafa, and chafa's colored blocks came out as an unrecognizable stripe pattern there. That happened with chafa's default colors and in 256-color mode (--chafa-canvas-mode INDEXED_256), on macOS 15 with Homebrew's chafa 1.18.3. The same image renders cleanly with chafa in kitty (above). On a Mac, use iTerm2, kitty, Ghostty or WezTerm if you want an image logo.

$ fastfetch --logo landscape.png --logo-type chafa --chafa-canvas-mode INDEXED_256 --logo-width 30
Screenshot: output of fastfetch --logo landscape.png --logo-type chafa --chafa-canvas-mode INDEXED_256 --logo-width 30
Apple's Terminal: the chafa image is unrecognizable (also without the 256-color mode) · Real screenshot from our lab, macOS 15.8
Logo typeHow it works
kittyfastfetch decodes the image and sends pixels with the kitty graphics protocol. The only type where fastfetch plays animations itself.
kitty-directSends the file to the terminal unchanged; the terminal decodes it. The wiki lists WezTerm and Warp (PNG, JPG, WebP…) and kitty and Ghostty (PNG only); Konsole doesn't support it.
kitty-icatRuns kitty's kitten icat, which has to be installed. Works inside tmux.
sixelEncodes the image as sixel graphics.
itermThe iTerm2 inline-image protocol (iTerm2, WezTerm, Konsole).
chafaConverts the image to colored Unicode blocks, so it works in any terminal with true color, at text resolution.
rawPrints a file you converted yourself (for example with img2sixel) as-is. Set --logo-width and --logo-height to its size in cells.

Each type has a shortcut that sets the type and the source at once: fastfetch --kitty ~/me.png is the same as --logo-type kitty --logo ~/me.png.

What your fastfetch build needs#

Image logos rely on libraries fastfetch loads only when you ask for an image. A missing library doesn't stop fastfetch from starting: the image just fails, and you get the normal ASCII logo instead.

SystemFor kitty and sixelFor chafaAnimated GIF
Windows, macOS, AndroidBuilt in since 2.69.0: the system's own image decoder (WIC, ImageIO, AImageDecoder)libchafaYes, kitty type (per the source code; GIF playback not tested on these systems)
Arch and other distributions with ImageMagick 7imagemagick (optional dependency)chafa (optional dependency)✓ tested on Arch
Ubuntu and Debian (ImageMagick 6)ImageMagick 6 librarieslibchafa0t64✗ "can not be animated by this build"

Two of these we checked directly:

  • The Ubuntu PPA package declares only libc6 as a dependency (apt-cache depends fastfetch), so neither library comes with it.
  • Arch lists imagemagick and chafa as optional dependencies (details).

To see what your build supports, run fastfetch --list-features and look for imagemagick6 or imagemagick7, chafa and Embedded sixel.

The chafa library, before and after#

On Ubuntu 24.04 with the PPA build but without libchafa, --logo-type chafa printed Logo: Failed to load / convert the image source and fell back to the Ubuntu logo. After sudo apt install libchafa0t64, the same command drew the image (second screenshot above):

$ fastfetch --logo landscape.png --logo-type chafa --show-errors
Screenshot: output of fastfetch --logo landscape.png --logo-type chafa --show-errors
Without libchafa: the error, then the normal ASCII logo · Real screenshot from our lab, Ubuntu 24.04, kitty 0.32.2

Size and position#

config.jsonc
{
  "$schema": "https://github.com/fastfetch-cli/fastfetch/raw/dev/doc/json_schema.json",
  "logo": {
    "type": "kitty",
    "source": "~/Pictures/me.png",
    "width": 30,
    "padding": { "right": 3 }
  }
}

width and height are in terminal cells, not pixels. If you set only one, the aspect ratio is kept; if you set neither, the image is drawn at its original size, which is usually far too big. To put the image above the text instead of beside it, set "position": "top". "auto" (new in 2.70.0) does that only when fewer than 32 columns would be left for the text. padding.right (default 4) is the gap between image and text; padding.top only applies with "position": "top".

Animated GIF logos (and "3D fastfetch")#

bash
fastfetch --logo ~/Pictures/spin.gif --logo-type kitty --logo-animation-frame 0
$ fastfetch --logo spin.gif --logo-type kitty --logo-animation-frame 0
Screenshot: output of fastfetch --logo spin.gif --logo-type kitty --logo-animation-frame 0
A 16-frame GIF playing as the logo, recorded from the kitty window · Real screenshot from our lab, Arch Linux, kitty 0.49.2, fastfetch 2.70.0, ImageMagick 7.1.2

Since 2.69.0 fastfetch can play GIF and APNG files, with some conditions:

  • Only the kitty type plays them. --logo-animation-frame 0 means "play"; the default 1 shows the first frame as a still image, and any other number picks that frame. Negative numbers count from the end, but only in a config file ("animationFrame": -1), because the command line reads a leading - as an option.
  • On Linux and BSD, fastfetch must be built with ImageMagick 7. The source code leaves ImageMagick 6 out of animation support. On Ubuntu's PPA build (ImageMagick 6), the same command printed Logo: the image source can not be animated by this build and showed the Ubuntu logo. Windows and macOS builds take their frames from the system's decoder, so according to the source code they can play GIFs too; we only tested Linux.
  • iterm and kitty-direct pass the file to the terminal, which may animate it by itself. fastfetch has no control over that.
$ fastfetch --logo spin.gif --logo-type kitty --logo-animation-frame 4
Screenshot: output of fastfetch --logo spin.gif --logo-type kitty --logo-animation-frame 4
--logo-animation-frame 4: one still frame of the same GIF · Real screenshot from our lab, Arch Linux, kitty 0.49.2

What people mean by "3D fastfetch"#

fastfetch itself has no 3D mode. The spinning 3D logos you may have seen come from a separate program, fetch by areofyl, written in C, ISC license, about 1,100 GitHub stars. It renders your distribution's logo as a rotating 3D relief next to live system information. According to its README, it takes the logo from fastfetch when fastfetch is installed, it runs on Linux and macOS, and Arch users can get it from the AUR as fetch-git. We haven't tested it. If you just want motion, an animated GIF in kitty (above) is fastfetch's own way.

A random image every time#

config.jsonc
{
  "$schema": "https://github.com/fastfetch-cli/fastfetch/raw/dev/doc/json_schema.json",
  "logo": { "type": "kitty", "source": "~/Pictures/fetch/*.png", "width": 30 }
}

On Linux, macOS and BSD, fastfetch expands the source path like a shell does, and when a wildcard matches several files it picks one at random. We checked the randomness with three logo files and 30 runs each: from the command line the split was 11, 9 and 10; from a config file, 9, 10 and 11. EndeavourOS's optional config uses a shell command (find … | sort -R | head -1) for the same effect. The wildcard is simpler.

Pokémon sprites and other generated logos#

Any program that prints colored text can supply the logo. pokeget prints Pokémon sprites, and there are two ways to connect it:

pipe it in for one run
pokeget pikachu --hide-name | fastfetch --file-raw -
or run it from your config
{
  "$schema": "https://github.com/fastfetch-cli/fastfetch/raw/dev/doc/json_schema.json",
  "logo": { "type": "command-raw", "source": "pokeget random --hide-name" }
}
fastfetch with pokeget as the logo · real output
     ▄▄▄         ▄▄      runner@runnervm48cm3
    ▄▄▄▄    ▄▄▄▄▄▄▄▄▄    --------------------
   ▄▄▄▄▀ ▄▄▄▄▄▄▄▄▄▄▄▀    OS: Ubuntu 24.04.5 LTS (Noble Numbat) x86_64
 ▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▀      Kernel: Linux 7.0.0-1017-azure
▄▄▄▄▄▄▄▄▄▄▄▄▀▄▄▄▄▄       Uptime: 3 mins
▀▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▀       Shell: bash 5.2.21
▀▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄        CPU: AMD EPYC 7763 64-Core (4) @ 3.23 GHz
    ▄▄▄▄▄▄▄▄▄▄▄▀         Memory: 969.57 MiB / 15.61 GiB (6%)
     ▀▄▄▄▄▄▄▄▄▀
         ▀▀▄▀
Captured on GitHub's ubuntu24 runner, fastfetch 2.70.0, 2026-11-02.

Both worked in our test with pokeget 1.6.7. file-raw - reads the logo from standard input. command-raw runs a shell command every time fastfetch starts. The wiki calls command-raw "config only", but in 2.70.0 --logo-type command-raw --logo 'cmd' worked on the command line too. A command-raw logo runs whatever command the config contains, so read configs from other people before you use them.

Album art of what's playing#

Since 2.55.0 the special source media-cover shows the cover of the currently playing track, for example fastfetch --kitty media-cover. It needs a terminal image protocol and a player that reports cover art. We couldn't test it on our headless machines.

The image cache#

fastfetch caches converted images so later runs start faster. On Linux they live under ~/.cache/fastfetch/images/, keyed by the image's full path and the requested size. A cached image is redrawn when the source file changes. Changing an option such as the logo type doesn't refresh it, though, so run once with --logo-cache regen after such a change. --logo-cache false turns the cache off. In 2.69.0, --logo-cache replaced the old --logo-recache. Using the old flag now stops with --logo-recache has been replaced by --logo-cache regen, and the old config key logo.recache fails the same way.

Image not showing? The exact messages#

When an image can't be drawn, fastfetch quietly shows your distribution's ASCII logo instead. In our test, a missing file with no other options printed nothing at all on stderr. Add --show-errors to see the reason, then look it up here:

Message (with --show-errors)What it meansFix
Logo: Failed to resolve logo source: …fastfetch couldn't find a file at that path, and it's not a built-in logo name either. We got this message for a missing image and for a mistyped logo name (-l not-a-real-logo).Check the spelling (fastfetch --list-logos for names). Use an absolute path or ~/, not a relative one (see below).
Logo: Failed to load / convert the image sourceThe image library for this logo type isn't installed. We got it for chafa without libchafa.Install chafa / libchafa0t64, or ImageMagick for kitty and sixel on Linux (table).
Logo: the image source can not be animated by this buildYou asked for animation (--logo-animation-frame 0) on a Linux build without ImageMagick 7.Drop the option for a still image, or use a build with ImageMagick 7.
Logo: Image logo is not supported in pipe modeThe output is piped or redirected, or NO_COLOR is set (message from the source code).Run it in the terminal directly, or add --pipe false when testing.
Logo: getCharacterPixelDimensions() failedfastfetch couldn't learn the size of a character cell in pixels. Its output isn't going to a terminal (a pipe, a file, a script), or the terminal doesn't report its size.Run it directly in a terminal. With Powerlevel10k, put it above the instant prompt (why).

Relative paths are relative to where you are#

A relative path in your config is resolved against the current directory, not the config file's folder. In our test, --logo me.png worked from the folder containing the image, and from any other folder it failed with Failed to resolve logo source: me.png. Three ways that work from anywhere, all tested:

  • A path starting with ~/, which fastfetch expands itself.
  • An absolute path.
  • Just a file name, with the file in ~/.local/share/fastfetch/logos/. fastfetch looks in that folder ($XDG_DATA_HOME/fastfetch/logos/) when the name doesn't match anything else.

Other common problems#

  • Works in the terminal, not in a script or in | less: image logos need a real terminal. Piped output keeps the ASCII logo but never an image.
  • The image overlaps the text, or its top scrolls away: set both --logo-width and --logo-height, so the terminal reserves exactly that much room. The wiki also suggests running clear first.
  • The GIF shows a still frame: add --logo-animation-frame 0 and use the kitty type.
  • You changed the logo type and still see the old picture: run once with --logo-cache regen.
$ fastfetch --logo '~/Pictures/does-not-exist.png' --show-errors
Screenshot: output of fastfetch --logo '~/Pictures/does-not-exist.png' --show-errors
A missing file with --show-errors: the message, then the default logo · Real screenshot from our lab, Ubuntu 24.04, kitty 0.32.2

Questions#

Why is my fastfetch image not showing?

Run it again with --show-errors. The message tells you whether the file wasn't found, a library is missing, or fastfetch isn't connected to a terminal. The messages and fixes.

Can fastfetch show a GIF?

Yes, since 2.69.0, with --logo-type kitty --logo-animation-frame 0 in a terminal that supports the kitty graphics protocol. On Linux the build needs ImageMagick 7: we confirmed it on Arch, while Ubuntu's PPA build refuses.

Does fastfetch work with images in Windows Terminal?

Use --logo-type sixel. In our test with Windows Terminal 1.23 and fastfetch 2.70.0 from Scoop, a PNG appeared as a sixel logo with nothing else installed: Windows builds decode images with the system's own decoder.

How do I make the fastfetch logo 3D?

fastfetch has no 3D mode. The spinning 3D logos come from a separate program, fetch, which reuses fastfetch's logos. Details.

How do I show a Pokémon in fastfetch?

Install pokeget, then run pokeget random --hide-name | fastfetch --file-raw -, or set "logo": {"type": "command-raw", "source": "pokeget random --hide-name"} in your config. Tested example.