Navigation Menu

Skip to content

Instantly share code, notes, and snippets.

@andersevenrud
Last active April 22, 2024 15:59
Show Gist options
  • Save andersevenrud/015e61af2fd264371032763d4ed965b6 to your computer and use it in GitHub Desktop.
Save andersevenrud/015e61af2fd264371032763d4ed965b6 to your computer and use it in GitHub Desktop.
True Color (24-bit) and italics with alacritty + tmux + vim (neovim)

True Color (24-bit) and italics with alacritty + tmux + vim (neovim)

This should make True Color (24-bit) and italics work in your tmux session and vim/neovim when using Alacritty (and should be compatible with any other terminal emulator, including Kitty).

Testing colors

Running this script should look the same in tmux as without.

curl -s https://gist.githubusercontent.com/lifepillar/09a44b8cf0f9397465614e622979107f/raw/24-bit-color.sh >24-bit-color.sh
bash 24-bit-color.sh

colors

Configuration files

⚠️ IMPORTANT ⚠️ Don't set $TERM in your shell (zshrc, bashrc, etc.), but your terminal (alacritty).

Alacritty

In ~/.config/alacritty/alacritty.yml:

env:
  TERM: xterm-256color

tmux

In ~/.tmux.conf (or ~/.config/tmux/tmux.conf):

set -g default-terminal "tmux-256color"
set -ag terminal-overrides ",xterm-256color:RGB"

# Or use a wildcard instead of forcing a default mode.
# Some users in the comments of this gist have reported that this work better.
#set -sg terminal-overrides ",*:RGB"

# You can also use the env variable set from the terminal.
# Useful if you share your configuration betweeen systems with a varying value.
#set -ag terminal-overrides ",$TERM:RGB"

vim

In ~/.vimrc:

" You might have to force true color when using regular vim inside tmux as the
" colorscheme can appear to be grayscale with "termguicolors" option enabled.
if !has('gui_running') && &term =~ '^\%(screen\|tmux\)'
  let &t_8f = "\<Esc>[38;2;%lu;%lu;%lum"
  let &t_8b = "\<Esc>[48;2;%lu;%lu;%lum"
endif

syntax on
set termguicolors
colorscheme yourfavcolorscheme

neovim

If you use ~/.vimrc for your nvim configuration, use the above vim example because it's fully compatible.

💡 neovim recently (Dec 6th 2023) merged some changes that detects termguicolors automatically, so there's no need to set this in an upcoming release. I'll update this notice with a version once released as a public version.

In ~/.config/nvim/init.vim

set termguicolors
colorscheme yourfavcolorscheme

Or ~/.config/nvim/init.lua:

vim.o.termguicolors = true
vim.cmd'colorscheme yourfavcolorscheme'

Not working correctly ?

Check out the comments below for possible solutions.

And if you found another solution I would really appreciate if you left a comment with instructions and the following information:

  • OS/Distro + version
  • Vim or Neovim + version
  • Terminal name + version

Mentions

Shout-out to the nice folks that provided insightful feedback:

@sahibalejandro
Copy link

I recently discovered that you can use ENV variables inside your tmux.conf so you can have something like:

set -ag terminal-overrides ",$TERM:RGB"

This is useful in the case you're sharing (like me) your tmux.conf between computers and the value of $TERM is different for each one.

@andersevenrud
Copy link
Author

@sahibalejandro That's pretty sick! I've updated the document with this information :)

@phuongthuan
Copy link

Hi guys, I was following the instruction and I hit another problem.
When I change

set -g default-terminal "screen-256color"

to

set -g default-terminal "tmux-256color"

The problem is exactly like this: https://stackoverflow.com/questions/45931164/duplicated-characters-and-non-updating-input-using-tmux-in-zsh
I don't know why :(

@andersevenrud
Copy link
Author

@phuongthuan I haven't personally experienced this, but I would suspect that it has something to do with your configuration files related to either the shell or tmux. If you have some custom stuff there, try to start fresh with these instructions and slowly start adding your other stuff.

@Tony-Sol
Copy link

Tony-Sol commented Aug 2, 2022

Using

set -g default-terminal "tmux-256color"
set -ag terminal-overrides ",xterm-256color:RGB"

breaks tmux in alacritty with can't find terminal definition for tmux-256color error (as well as using tmux.conf without default-terminal and terminal-overrides declarations), but fonts and color in neovim are ok, but :checkhealth says

  - WARNING: Neither Tc nor RGB capability set. True colors are disabled. 'termguicolors' won't work properly.
    - ADVICE:
      - Put this in your ~/.tmux.conf and replace XXX by your $TERM outside of tmux:
          set-option -sa terminal-overrides ',XXX:RGB'
      - For older tmux versions use this instead:
          set-option -ga terminal-overrides ',XXX:Tc'

Using

set -g default-terminal "xterm-256color"

fixes opening tmux, neovim fonts are ok, but colors changed and :checkhealth says:

  - ERROR: $TERM should be "screen-256color" or "tmux-256color" in tmux. Colors might look wrong.
    - ADVICE:
      - Set default-terminal in ~/.tmux.conf:
          set-option -g default-terminal "screen-256color"
      - https://github.com/neovim/neovim/wiki/FAQ

Well, using

set -g default-terminal "screen-256color"
set -ag terminal-overrides ",xterm-256color:RGB"

fixes opening tmux, fixes neovim colors and :checkhealth, but breaks neovim fonts

What a mess!

UPD: After updating ncurses by this guide, tmux-256color is finally supported and all works good

@krmckone
Copy link

krmckone commented Aug 4, 2022

Only thing that worked for me: adding set -ag terminal-overrides ",alacritty:RGB" to .tmux.conf file

macOS v12.4
NVIM v0.7.2
alacritty v0.10.1

@johanvx
Copy link

johanvx commented Aug 6, 2022

Thanks so much!

I use iTerm2 and Alacritty at the same time, and the following settings work fine on my machine.

Versions

  • macOS 13.0 Beta
  • iTerm2 3.4.16
  • alacritty 0.10.1
  • tmux 3.3a
  • NVIM 0.8.0-dev

Configurations

  • iTerm2

    Preferences -> Profiles -> Terminal
    
    Terminal Emulation
      Report terminal type: xterm-256color
    
  • Alacritty

    # ~/.config/alacritty/alacritty.yml
    env:
      TERM: xterm-256color
  • Tmux

    # .tmux.conf
    set -g default-terminal "xterm-256color"
    set -ag terminal-overrides ",xterm-256color:RGB"

@gcarlos64
Copy link

Tried all the things but nothing works

OS: Voidlinux
Alacritty: 0.10.1
Tmux: 3.3a

@wonbinbk
Copy link

wonbinbk commented Aug 27, 2022

I followed all your instructions but still in tmux it couldn't display 24-bit color.
However, just by luck I found another guide and the only difference is in this:

set -ag terminal-overrides ",xterm-256color:RGB" -> set -sg terminal-overrides ",*:RGB"

And there we go, I have 24-bit color in tmux.

@fiskhest
Copy link

fiskhest commented Sep 1, 2022

I followed all your instructions but still in tmux it couldn't display 24-bit color. However, just by luck I found another guide and the only difference is in this:

set -ag terminal-overrides ",xterm-256color:RGB" -> set -sg terminal-overrides ",*:RGB"

And there we go, I have 24-bit color in tmux.

Same here on arch linux with latest tmux and alacritty. I tried every suggestion in this thread but only after setting set -sg terminal-overrides ",*:RGB" and restarting the tmux server I had true 24b support.

@EriKWDev
Copy link

If you have nvim installed, you can open it and type the command :checkhealth and it will give some debugging tips for tmux colors as well

@wangyandongnx
Copy link

Thanks so much!

I use iTerm2 and Alacritty at the same time, and the following settings work fine on my machine.

Versions

  • macOS 13.0 Beta
  • iTerm2 3.4.16
  • alacritty 0.10.1
  • tmux 3.3a
  • NVIM 0.8.0-dev

Configurations

  • iTerm2
    Preferences -> Profiles -> Terminal
    
    Terminal Emulation
      Report terminal type: xterm-256color
    
  • Alacritty
    # ~/.config/alacritty/alacritty.yml
    env:
      TERM: xterm-256color
  • Tmux
    # .tmux.conf
    set -g default-terminal "xterm-256color"
    set -ag terminal-overrides ",xterm-256color:RGB"

Thanks! It works for me.

@Mohamed-Ibrahim-01
Copy link

Thank you so much, finally it worked 🎉

This line from the comments helped also set -sg terminal-overrides ",*:RGB"

@andersevenrud
Copy link
Author

andersevenrud commented Oct 7, 2022

@wonbinbk I've added your solution to this document as it seems other users have success in using this as well.

Haven't been able to reproduce the issues with original instructions even on the same systems as reported, but it seems like this area is filled with dragons 😅

Thanks!

@tobias-edwards
Copy link

tobias-edwards commented Nov 23, 2022

This is what worked for me:

alacritty.yml

env:
  TERM: xterm-256color

.tmux.conf

set -g default-terminal 'xterm-256color'
set -as terminal-overrides ',xterm*:Tc:sitm=\E[3m'

Thank you!

  • OS: macOS@12.6.1 (Monterey, M1)

Almost worked perfectly but the terminal override inappropriately rendered \E[3m characters in Neovim, so I ended up fiddling and tweaking using these guides until colours, symbols, bold, italics all worked for me:

@p1xelHer0
Copy link

p1xelHer0 commented Nov 23, 2022

This is what worked for me:

alacritty.yml

env:
  TERM: xterm-256color

.tmux.conf

set -g default-terminal 'xterm-256color'
set -as terminal-overrides ',xterm*:Tc:sitm=\E[3m'

Thank you!

This worked for me as well, thanks!

- macOS Monterey @ 12.6.1
- Alacritty      @ 0.11.0
- tmux           @ 3.3a

@matheustanaka
Copy link

I followed all your instructions but still in tmux it couldn't display 24-bit color. However, just by luck I found another guide and the only difference is in this:

set -ag terminal-overrides ",xterm-256color:RGB" -> set -sg terminal-overrides ",*:RGB"

And there we go, I have 24-bit color in tmux.

Thanks for that solution!
I'm using pop os with alacritty neovim and tmux, but when I installed tmux, my colors on neovim broken. After put set -sg terminal-overrides ",*:RGB" everything works again.

@mikeslattery
Copy link

ssh does not work correctly for one of my other desktops, probably because tmux-256color is unknown to it. I had to SetEnv to my ~/.ssh/config. There might be a better way, but this works well.

Host otherdesktop
  Hostname otherdesktop
  SetEnv TERM=xterm

Ad-hoc alternate: TERM=xterm ssh otherdesktop

@anaetrezve
Copy link

Works like charm. Thank you so much

@i6iesma
Copy link

i6iesma commented Dec 30, 2022

Thank you!!!

@chalop
Copy link

chalop commented Jan 10, 2023

Hi guys, I was following the instruction and I hit another problem. When I change

set -g default-terminal "screen-256color"

to

set -g default-terminal "tmux-256color"

The problem is exactly like this: https://stackoverflow.com/questions/45931164/duplicated-characters-and-non-updating-input-using-tmux-in-zsh I don't know why :(

I am also having this issue, any solutions yet?

@snakejke
Copy link

snakejke commented Jan 16, 2023

Not everyone have terminfo "tmux-256color" in /usr/share/terminfo/t/tmux-256color (system-wide) or ~/.terminfo/t/tmux-256color (user only)
So...There is good Guide how to get tmux-256color ------ >>>> https://gist.github.com/bbqtd/a4ac060d6f6b9ea6fe3aabe735aa9d95 ( work for any distro )

@rgurov
Copy link

rgurov commented Jan 19, 2023

Thank you!

@Dsypasit
Copy link

good for me. Love you!

@mndscp
Copy link

mndscp commented Feb 14, 2023

set -ag terminal-overrides ",$TERM:RGB"

Thank you!

I only needed to set this one line in my tmux.conf.
Nothing else changed in neither environment variables nor Alacritty config.

Arch Linux, tmux in Alacritty.

Note: When I tried to do this a few times before I might have gotten the solution but I must have missed it because colors didn't update before typing this once and opening a new terminal afterwards: tmux kill-server

@ishanSharma07
Copy link

Thank you!!!

OSX, Alacritty, ssh'ed to a remote desktop, neovim inside tmux on the remote desktop.

@sokinpui
Copy link

sokinpui commented Apr 8, 2023

I find that when I press backspace inside tmux, it convert to white space. also the color is also inconsisent outside and inside tmux
image

MacOS : 12.6
Vim : 9.0
Alacritty : 0.11.0

inside alacritty.yml:

font:
  normal:
    family: Menlo 

  size: 14.0

Inside .vimrc:

set background=dark
if !has('gui_running') && &term =~ '^\%(screen\|tmux\)'
  let &t_8f = "\<Esc>[38;2;%lu;%lu;%lum"
  let &t_8b = "\<Esc>[48;2;%lu;%lu;%lum"
endif
syntax on
set termguicolors
colorscheme onedark

Inside .tmux.conf:

set -g default-terminal "tmux-256color"
set -ag terminal-overrides ",xterm-256color:RGB"

@napisani
Copy link

here is what worked for me
osx 12.1
alacritty 0.11.0
tmux 3.3a

#alacritty.yml 
env:
  TERM: screen-256color
#.tmux.conf
set -g default-terminal "screen-256color"
set -sg terminal-overrides ",*:RGB"
#.vimrc
set termguicolors

@LeFede
Copy link

LeFede commented May 1, 2023

I tried every config in this article and still cannot get it to work.

I'm using Arch and Alacritty

image

however, using the default console works

image

any ideas?

EDIT: setting enable_rgb: true in alacritty.yml did the trick

@erenard
Copy link

erenard commented May 25, 2023

@LeFede This worked for me with Arch/Alacritty/tmux

alacritty.yaml

env:
  TERM: alacritty-direct

tmux.conf

set-option -a terminal-overrides ",alacritty:RGB"

default-terminal was not needed in the tmux.conf

@huatao76
Copy link

huatao76 commented Jul 1, 2023

@LeFede This worked for me with Arch/Alacritty/tmux

alacritty.yaml

env:
  TERM: alacritty-direct

tmux.conf

set-option -a terminal-overrides ",alacritty:RGB"

default-terminal was not needed in the tmux.conf

thank you

@jeremyjjbrown
Copy link

None of these work for me on alacritty..

Same stuff every time I try to adopt tmux. Spend an hour trying everything on the internet.

Clipboard is a PITA, OSC52 support doesn't work.
Colors don't work.
Mouse scrolling doesn't work.

It's absurd this tool is so evangelized.

@BhawickJain
Copy link

BhawickJain commented Jul 17, 2023

When following these instructions and changing the tmux config, I found that my backspace key created space characters.

this was resolved after restarting tmux server

tmux kill-server

hope this help anyone, thank you for this awesome gist!

--
macOS (11.7.8)
NVIM (0.9.1)
alacritty (0.11.0)
tmux (3.3a)

@djhaskin987
Copy link

Fedora 38, Konsole + TMux 3.3a + neovim 0.9.1 .
The following worked for me:

set -sa default-terminal "screen-256color"
set -sa terminal-features ",xterm-256color:RGB"

Notably, I could NOT have tmux-256color as my default terminal even though I downloaded it off the internet and so I know I had it on hand. It had to be screen.

@zach-is-my-name
Copy link

Not everyone have terminfo "tmux-256color" in /usr/share/terminfo/t/tmux-256color (system-wide) or ~/.terminfo/t/tmux-256color (user only) So...There is good Guide how to get tmux-256color ------ >>>> https://gist.github.com/bbqtd/a4ac060d6f6b9ea6fe3aabe735aa9d95 ( work for any distro )

A little Ai model told me you can use infocmp xterm-256color to check if you have this (the paths quoted above were blank, but infocmp found the terminfo here /lib/terminfo/t/tmux-256color (ubuntu 22.04)

@pavan-kumarv
Copy link

This solved my issue as well thanks 😊

@ericragsdale
Copy link

OSX Ventura
Alacritty 0.12.2
tmux 3.3a
nvim 0.9.2

Problem

When using neovim within tmux, my colors were off and it would not display italics or undercurls.

Solution

I had trouble with the provided solution, but it pointed me in the right direction. This is what works for me.

alacritty

I left the env: section commented out

tmux.conf

set-option -sa terminal-features ',alacritty:RGB'
set-option -ga terminal-features ",alacritty:usstyle"
set-option -ga terminal-overrides ',alacritty:Tc'
set -g default-terminal "alacritty"

nvim

termguicolors = true

@fishel-feng
Copy link

I find that when I press backspace inside tmux, it convert to white space. also the color is also inconsisent outside and inside tmux image

MacOS : 12.6
Vim : 9.0
Alacritty : 0.11.0

inside alacritty.yml:

font:
  normal:
    family: Menlo 

  size: 14.0

Inside .vimrc:

set background=dark
if !has('gui_running') && &term =~ '^\%(screen\|tmux\)'
  let &t_8f = "\<Esc>[38;2;%lu;%lu;%lum"
  let &t_8b = "\<Esc>[48;2;%lu;%lu;%lum"
endif
syntax on
set termguicolors
colorscheme onedark

Inside .tmux.conf:

set -g default-terminal "tmux-256color"
set -ag terminal-overrides ",xterm-256color:RGB"

@sokinpui The phenomenon I encountered before is the same as yours. You can try this set of configurations. It works for me.

alacrity

env:
  TERM: screen-256color

tmux

set -g default-terminal "screen-256color"
set-option -sa terminal-overrides ',screen-256color:Tc'

@nickgnd
Copy link

nickgnd commented Oct 24, 2023

Hey 👋
This combination of settings works fine for me

# .alacritty.yml

env:
  TERM: alacritty

and in my tmux config:

# tmux.conf

set-option -g default-terminal "screen-256color"
  • OS/Distro: MacOS Ventura 13.6
  • Vim: VIM - Vi IMproved 9.0
  • Terminal: alacritty 0.12.3 (5efb069)
  • Tmux: tmux 3.3a

Hope it can help ✌️

@antonkesy
Copy link

Alacritty versions >= 0.13.0 (moved to TOML for config)

[env]
TERM="xterm-256color"

@Hritik14
Copy link

Hritik14 commented Nov 7, 2023

Italics in my vim were messed up, if someone has this problem, you can verify by running

echo -e "\e[3mitalic\e[0m"

if output is in italics then it's a vim problem, otherwise something else is wrong.

I had to add the following in my vimrc as per this for italics.

let &t_ZH="\e[3m"
let &t_ZR="\e[23m"

using macvim, tmux and iterm2

@PThorpe92
Copy link

Thank you so much for this..

I legit switched to kitty for months over this issue, I had tried every fix out there (what did it was the ENV) so glad to be back with alacritty

@jonnovaretti
Copy link

AMAZING!!! Thanks

@mikeslattery
Copy link

mikeslattery commented Dec 11, 2023

BREAKING NEWS!

(edits: I was wrong. Only the neovim changes aren't necessary.)

tl;dr - This gist is no longer necessary with latest Neovim.

Neovim now checks for 256 color compatibility and automatically sets termguicolors. Alacritty with default $TERM value ("alacritty") works fine. I just tested it with nightly.

Recent changes announced at the Neovim conference a few days ago have made the changes in this gist unnecessary for latest builds. However, I'm sure as of this moment many people are using versions that don't yet support this and that will likely be the case for a few weeks. I don't know the exact version this was added, or which versions have it other than latest nightly.

Of course, it will still be necessary for Vim.

@andersevenrud
Copy link
Author

Thanks for the heads-up @mikeslattery ! This is great news :)

I'll update this article and follow up when this goes into a public release.

@mikeslattery
Copy link

mikeslattery commented Dec 13, 2023

Looks like I wasn't correct. You still need the tmux and alacritty config. You just don't need the neovim config anymore.

Quick test for Linux. As of this comment it works for nightly and not for release.

#!/bin/bash
# Test for truecolor.  Should see bands of smooth gradient colors.

# To test  installed nvim, set this to "nvim" and comment out #linux nvim install block, and remove rm $NVIM line
NVIM=/tmp/nvim

# Linux nvim install
NIGHTLY=https://github.com/neovim/neovim/releases/download/nightly/nvim.appimage
RELEASE=https://github.com/neovim/neovim/releases/download/stable/nvim.appimage
# Change to $NIGHTLY to see it working correctly.
curl -Lo $NVIM $RELEASE
chmod +x $NVIM

# Reconfigure
echo '
set -ag terminal-overrides ",xterm-256color:RGB"
' > /tmp/.tmux.conf
echo '
env:
  TERM: xterm-256color
' > /tmp/alacritty.yaml

# Test
TEST=https://gist.githubusercontent.com/lifepillar/09a44b8cf0f9397465614e622979107f/raw/24-bit-color.sh
alacritty --config-file /tmp/alacritty.yaml \
  -e tmux -f /tmp/.tmux.conf -L nvim new-session \
  $NVIM --clean  "+terminal curl -s $TEST | bash" "+set termguicolors?"
# old way:
# $NVIM --clean  +"set termguicolors" "+colorscheme ron" "+terminal curl -s $TEST | bash"

# Cleanup
rm "$NVIM"
rm /tmp/.tmux.conf /tmp/alacritty.yaml

@andersevenrud
Copy link
Author

Appreciate the detailed follow-up on this @mikeslattery. I've updated the article to reflect this 👍

@n0099
Copy link

n0099 commented Feb 29, 2024

echo 'set -as terminal-overrides ",'"$(echo ${TERM%%-*})"'*:Tc"' >> ~/.tmux.conf

https://github.com/tmux/tmux/wiki/FAQ#how-do-i-use-rgb-colour

tmux must be told that the terminal outside supports RGB colour. This is done by specifying the RGB or Tc terminfo(5) flags. RGB is the official flag, Tc is a tmux extension.

With tmux 3.2 and later this can be added with the terminal-features option:

set -as terminal-features ",gnome*:RGB"

Or for any tmux version the terminal-overrides option:

set -as terminal-overrides ",gnome*:Tc"

and replace gnome with the result of echo ${TERM%%-*} (the first part of $TERM delimited by -) from the terminal emulator that you are currently using outside tmux such as putty or xterm.

@ferBV
Copy link

ferBV commented Mar 24, 2024

Just what I needed, thank you a lot.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment