# 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.

Canonical page: https://fastfetch.dev/logos/images/ · Checked against fastfetch 2.71.0 · Updated 2026-11-06 · Independent guide, not affiliated with the fastfetch-cli project.

## 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:

![Screenshot: output of fastfetch --logo landscape.png --logo-width 30](/assets/img/lab/image-auto.webp)  
*$ fastfetch --logo landscape.png --logo-width 30. Picked automatically in kitty*

![Screenshot: output of fastfetch --logo landscape.png --logo-type chafa --logo-width 30](/assets/img/lab/image-chafa.webp)  
*$ fastfetch --logo landscape.png --logo-type chafa --logo-width 30. --logo-type chafa: the same image as colored text*

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

| Terminal | Use | What `auto` picks |
| --- | --- | --- |
| kitty | `--logo-type kitty` (also plays GIFs) | kitty protocol ✓ tested |
| Ghostty, WezTerm, Konsole, Warp | `--logo-type kitty` | kitty protocol |
| iTerm2 | `--logo-type iterm` | iTerm protocol |
| Windows Terminal | `--logo-type sixel` ✓ tested | chafa |
| Apple's Terminal (macOS) | No good option: chafa came out unrecognizable in our test. Use iTerm2, kitty, Ghostty or WezTerm for images | chafa ✓ tested |
| Anything else: GNOME Terminal, Alacritty, the Linux console… | `--logo-type chafa` | chafa ✓ 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](/logos/#spin)).

We tested kitty, Windows Terminal and Apple's Terminal ourselves; the other rows reflect the source code and the official [logo documentation](https://github.com/fastfetch-cli/fastfetch/wiki/Logo-options). 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:

![Screenshot: output of fastfetch --logo landscape.png --logo-type sixel --logo-width 30](/assets/img/lab/windows-terminal-sixel.webp)  
*$ fastfetch --logo landscape.png --logo-type sixel --logo-width 30. Windows Terminal 1.23: a sixel image logo, no extra software needed*

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](#quick)). On a Mac, use iTerm2, kitty, Ghostty or WezTerm if you want an image logo.

![Screenshot: output of fastfetch --logo landscape.png --logo-type chafa --chafa-canvas-mode INDEXED_256 --logo-width 30](/assets/img/lab/macos-terminal-chafa.webp)  
*$ 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)*

| Logo type | How it works |
| --- | --- |
| `kitty` | fastfetch decodes the image and sends pixels with the kitty graphics protocol. The only type where fastfetch plays animations itself. |
| `kitty-direct` | Sends 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-icat` | Runs kitty's `kitten icat`, which has to be installed. Works inside tmux. |
| `sixel` | Encodes the image as sixel graphics. |
| `iterm` | The iTerm2 inline-image protocol (iTerm2, WezTerm, Konsole). |
| `chafa` | Converts the image to colored Unicode blocks, so it works in any terminal with true color, at text resolution. |
| `raw` | Prints 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.

| System | For kitty and sixel | For chafa | Animated GIF |
| --- | --- | --- | --- |
| Windows, macOS, Android | Built in since 2.69.0: the system's own image decoder (WIC, ImageIO, AImageDecoder) | libchafa | Yes, kitty type (per the source code; GIF playback not tested on these systems) |
| Arch and other distributions with ImageMagick 7 | `imagemagick` (optional dependency) | `chafa` (optional dependency) | ✓ tested on Arch |
| Ubuntu and Debian (ImageMagick 6) | ImageMagick 6 libraries | `libchafa0t64` | ✗ "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](/install/arch/#optional)).

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):

![Screenshot: output of fastfetch --logo landscape.png --logo-type chafa --show-errors](/assets/img/lab/image-chafa-missing-lib.webp)  
*$ fastfetch --logo landscape.png --logo-type chafa --show-errors. Without libchafa: the error, then the normal ASCII logo*

## Size and position

*config.jsonc*

```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
```

![Screenshot: output of fastfetch --logo spin.gif --logo-type kitty --logo-animation-frame 0](/assets/img/lab/anim-kitty.webp)  
*$ fastfetch --logo spin.gif --logo-type kitty --logo-animation-frame 0. A 16-frame GIF playing as the logo, recorded from the kitty window*

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.

![Screenshot: output of fastfetch --logo spin.gif --logo-type kitty --logo-animation-frame 4](/assets/img/lab/anim-still.webp)  
*$ fastfetch --logo spin.gif --logo-type kitty --logo-animation-frame 4. --logo-animation-frame 4: one still frame of the same GIF*

### 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](https://github.com/areofyl/fetch), 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*

```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](https://github.com/talwat/pokeget-rs) prints Pokémon sprites, and there are two ways to connect it:

*pipe it in for one run*

```bash
pokeget pikachu --hide-name | fastfetch --file-raw -
```

*or run it from your config*

```jsonc
{
  "$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 (Linux, fastfetch 2.70.0)*

```
     ▄▄▄         ▄▄      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%)
     ▀▄▄▄▄▄▄▄▄▀
         ▀▀▄▀
```

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 means | Fix |
| --- | --- | --- |
| `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](#paths)). |
| `Logo: Failed to load / convert the image source` | The 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](#build)). |
| `Logo: the image source can not be animated by this build` | You 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 mode` | The 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() failed` | fastfetch 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](/startup/#p10k)). |

### 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`.

![Screenshot: output of fastfetch --logo '~/Pictures/does-not-exist.png' --show-errors](/assets/img/lab/image-missing.webp)  
*$ fastfetch --logo '~/Pictures/does-not-exist.png' --show-errors. A missing file with --show-errors: the message, then the default logo*

## 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](#troubleshooting).

### 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](https://github.com/areofyl/fetch), which reuses fastfetch's logos. [Details](#3d).

### 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](#pokemon).

---

Contact: hello@fastfetch.dev · Official project: https://github.com/fastfetch-cli/fastfetch
