Skip to content

Help

Jump to bottom
InterCentury edited this page Oct 3, 2026 · 2 revisions

Help and Troubleshooting

Find your problem in the list below. Each entry gives the likely cause and the fix.

On this page

Quick checks

Most problems are solved by one of these:

  1. Open a new terminal window and try again.
  2. Use Windows Terminal 1.22 or newer if you use images, GIFs or video.
  3. Check the config file for a missing or extra comma.
  4. If the config is broken beyond repair, delete it and run binaryfetch to get a fresh default.

Tip

Messages that start with Warning: when BinaryFetch runs tell you exactly what failed, for example a file that could not be opened. Read them first.

Installation and the command

binaryfetch is not recognised

Cause: the terminal was opened before the install, so it does not know the new PATH. Or the install folder is not in PATH.

Fix:

  1. Close the terminal and open a new one.
  2. If it still fails, sign out of Windows and back in, or restart.
  3. Check where Windows finds it:
where binaryfetch
  1. As a test, run it by its full path. With the default install folder:
"C:\Program Files\BinaryFetch\BinaryFetch.exe"

If the full path works but binaryfetch does not, the PATH entry is missing. Reinstall, or add the install folder to your system PATH yourself.

Note

The installer needs administrator rights, because it adds BinaryFetch to the system PATH.

The installer does not start or asks for permission

The installer runs as administrator. Accept the Windows prompt. If you cannot, ask an administrator to install it.

It still shows an old version after installing

An older copy may be earlier in your PATH, or the terminal is using a cached command. Open a new terminal and run where binaryfetch to see which file runs.

Configuration

The config file is:

C:\Users\Public\BinaryFetch\BinaryFetch_Config.jsonc

Nothing is shown, or whole sections are missing

Cause: the file has a syntax error. The usual culprits are a missing comma, an extra comma after the last item, or a missing quote.

Fix:

  1. Look at the last thing you edited.
  2. Make sure there is no comma after the last item in a block or list.
  3. If you cannot find the mistake, delete the config file and run binaryfetch to create a fresh default.

Caution

When the config cannot be read, BinaryFetch treats it as not loaded and does not show the information sections. It does not point at the line with the error.

A section does not appear

A section is shown only if both of these are true:

  • its name is in section_order
  • its own enabled is true

Some sections are off by default, for example compact_network_connection and most detailed_* sections. Turn them on and add them to section_order.

My changes have no effect

  • Check that you edited C:\Users\Public\BinaryFetch\BinaryFetch_Config.jsonc.
  • Save the file, then run binaryfetch again.
  • If both BinaryFetch_Config.jsonc and an older BinaryFetch_Config.json exist, the .jsonc file is used.
  • If only the older .json file exists, that one is used.

I want to reset to the defaults

Delete the config file (and any older .json file), then run binaryfetch. A fresh default file is created.

A colour looks wrong or turns white

Cause: the colour name in that section does not exist in colors.

Fix: use a name that is defined in colors, or add the colour there. Put hex or RGB values in colors only, and refer to them by name everywhere else.

Colours, symbols and text

Symbols or box lines show as ? or odd characters

Cause: the terminal font does not have those glyphs.

Fix:

  • Use Windows Terminal with a font that supports the symbols, such as Cascadia Code.
  • Or change the prefix and label text in the config to plain characters.

Emoji are misaligned or the wrong width

Cause: the terminal and font disagree about how wide an emoji is.

Fix:

  • In the emoji section, set style to "text".
  • Or set enabled to false to remove emoji completely.

Columns do not line up in a detailed section

The spaces inside label_suffix line the colons up. If you renamed a label, add or remove spaces in its label_suffix until the colons align.

ASCII art

My custom art does not appear

  • Edit C:\Users\Public\BinaryFetch\BinaryArt.txt.
  • Save it as plain text in UTF-8.
  • Make sure no higher-priority art is enabled. Video, then GIF, then Image all take priority over ASCII art.
  • Make sure Ascii_Art has "enabled": true.

The art has no colour

Check that show_colors in ascii_color_prefixes is true, and that the art uses $1, $2, ... codes.

The art lines up badly

Use a monospaced font in your terminal. Characters that are wider than one column, such as some symbols, can shift the layout.

I deleted BinaryArt.txt

Run binaryfetch again. If the file is missing, it is recreated with the default art.

Images, GIFs and videos

For all art options, see the Art, Image, GIF and Video page.

Important

Images, GIFs and videos need a terminal that supports Sixel, such as Windows Terminal 1.22 or newer. They are not available on Linux.

Nothing appears, or the screen fills with random characters

Cause: the terminal does not support Sixel, so the picture data is printed as text.

Fix:

  • Use Windows Terminal 1.22 or newer. Open Windows Terminal, go to Settings, and choose About to see your version.
  • To update it, use the Microsoft Store, or run:
winget upgrade Microsoft.WindowsTerminal
  • The older Windows console window and many other terminals do not support Sixel.

A warning says the file could not be opened

Cause: the path is wrong, or the file cannot be decoded.

Fix:

  • Check the path and the file name.
  • In JSON, write backslashes twice or use forward slashes:
"G:/screenshot/sky.jpg"     valid
"G:\\screenshot\\sky.jpg"   valid
"G:\screenshot\sky.jpg"     invalid

A different picture appears than the one I enabled

Only one type is drawn, in this order of priority:

Video  >  Gif  >  Image  >  Ascii Art

Set the higher-priority types to "enabled": false.

The picture is far too big or too small

Change image_size_percentage. It scales the picture from its original pixel size, so 100 is original size. A large photo needs a small percentage.

The picture and the information text do not line up

Cause: BinaryFetch worked out the terminal's character size incorrectly, for example with unusual display scaling.

Fix:

  • For video, set cell_width_px and cell_height_px to your terminal's character size in pixels. Leave both at 0 for automatic detection.
  • For images and GIFs, adjust image_size_percentage and the padding values until the layout fits.

The video is upside down

Set flip_vertical to true in the Video section.

The video is choppy or slow

  • Lower image_size_percentage.
  • Lower fps, for example to 24 or 15.

Larger pictures and higher frame rates cost more processing and send more data to the terminal.

The video does not open

Cause: Windows cannot play that format, or the codec is missing.

Fix: convert the video to MP4 with H.264, which Windows plays everywhere. The warning shown at startup includes an error code you can include in a bug report.

The video has sheared lines or a green line at the edge

This was fixed in v1.8. Update to the latest version if you still see it.

The video has no sound

This is expected. BinaryFetch shows the picture only and does not play audio.

The GIF takes a long time to start

All GIF frames are prepared before playback begins. A long or high-resolution GIF takes longer and uses more memory. Lower image_size_percentage.

I cannot get out of the GIF

GIFs play live. Press Ctrl + C to exit.

Transparent parts of my PNG are wrong

Pixels that are mostly transparent are not drawn, so your terminal background shows through. All other pixels are fully opaque. There is no partial blending.

Updating

My settings disappeared after updating

From v1.8, the installer deletes the folder C:\Users\Public\BinaryFetch before installing. This removes your config and BinaryArt.txt, and prevents conflicts with an old config. BinaryFetch creates fresh default files on first run.

To keep your settings: copy C:\Users\Public\BinaryFetch somewhere safe before you run the installer. After installing, run binaryfetch once, then copy your values into the new config.

Warning

Do not copy an old config over the new one wholesale. Newer versions can add or rename options, which is what the cleanup avoids. Copy only the values you want to keep.

The old version is still installed

You do not need to uninstall first. Run the new installer. If a problem remains, uninstall from Settings > Apps, then install again.

Frequently asked questions

Does it work on Linux? Not for images, GIFs and videos. As of v1.8 the Linux build supports ASCII art only.

Can I use my own ASCII art? Yes. Edit C:\Users\Public\BinaryFetch\BinaryArt.txt.

Can I use a video, a GIF and an image at the same time? No. Only one type is drawn, chosen by priority: Video, then Gif, then Image, then ASCII art.

Does the video play sound? No. Only the picture is shown.

Which terminals show images? Terminals with Sixel support, such as Windows Terminal 1.22 or newer.

Does BinaryFetch need administrator rights to run? No. Only the installer does.

Does uninstalling remove my settings? No. The uninstaller removes the program and its PATH entry, but leaves C:\Users\Public\BinaryFetch. Delete that folder yourself if you want everything gone.

Where is the config file? C:\Users\Public\BinaryFetch\BinaryFetch_Config.jsonc

Reporting a problem

If none of the above solves it, open an issue on the BinaryFetch GitHub repository: https://github.com/BinaryFetch-CLI/BinaryFetch/issues

Please include:

  • your BinaryFetch version and Windows version
  • the terminal you use and its version
  • what you expected and what happened
  • any Warning: text, copied exactly
  • a screenshot, if the problem is visual
  • the relevant part of your config, with personal paths removed

Tip

To test with a clean setup, rename your config file and run binaryfetch. If the problem disappears, it comes from your config.

Clone this wiki locally