Terminal colours are tricky
Yesterday I was thinking about how long it took me to get a colorscheme in my terminal that I was mostly happy with (SO MANY YEARS), and it made me wonder what about terminal colours made it so hard. So I asked people on Mastodon what problems they’ve run into with colours in the terminal, and I got a ton of interesting responses! Let’s talk about some of the problems and a few possible ways to fix them. One of the top complaints was “blue on black is hard to read”. Here’s an example of that: if I open Terminal.app, set the background to black, and run , the directories are displayed in a blue that isn’t that easy to read: To understand why we’re seeing this blue, let’s talk about ANSI colours! Your terminal has 16 numbered colours – black, red, green, yellow, blue, magenta, cyan, white, and “bright” version of each of those. Programs can use them by printing out an “ANSI escape code” – for example if you want to see each of the 16 colours in your terminal, you can run this Python program: This made me wonder – if blue is colour number 5, who decides what hex color that should correspond to? The answer seems to be “there’s no standard, terminal emulators just choose colours and it’s not very consistent”. Here’s a screenshot of a table from Wikipedia , where you can see that there’s a lot of variation: Bright yellow on white is even worse than blue on black, here’s what I get in a terminal with the default settings: That’s almost impossible to read (and some other colours like light green cause similar issues), so let’s talk about solutions! If you’re annoyed by these colour contrast issues (or maybe you just think the default ANSI colours are ugly), you might think – well, I’ll just choose a different “blue” and pick something I like better! There are two ways you can do this: Way 1: Configure your terminal emulator : I think most modern terminal emulators have a way to reconfigure the colours, and some of them even come with some preinstalled themes that you might like better than the defaults. Way 2: Run a shell script : There are ANSI escape codes that you can print out to tell your terminal emulator to reconfigure its colours. Here’s a shell script that does that , from the base16-shell project. You can see that it has a few different conventions for changing the colours – I guess different terminal emulators have different escape codes for changing their colour palette, and so the script is trying to pick the right style of escape code based on the environment variable. I prefer to use the “shell script” method, because: some advantages of configuring colours in your terminal emulator: This is what my shell has looked like for probably the last 5 years (using the solarized light base16 theme), and I’m pretty happy with it. Here’s : Okay, so let’s say you’ve found a terminal colorscheme that you like. What else can go wrong? Here’s what some output of , a alternative, looks like in my colorscheme: The contrast is pretty bad here, and I definitely don’t have that lime green in my normal colorscheme. What’s going on? We can see what color codes is using using the program to capture its output including the color codes: means “set the foreground color to color ”. Terminals don’t only have 16 colours – many terminals these days actually have 3 ways of specifying colours: So is using one of the colours from the extended 256-color set. (a alternative) does something similar – here’s what it looks like by default in my terminal. This looks fine though and it really seems like it’s trying to work well with a variety of terminal themes. I think it’s interesting that some of these newer terminal tools ( , , , and probably more) have support for arbitrary custom themes. I guess the downside of this approach is that the default theme might clash with your terminal’s background, but the upside is that it gives you a lot more control over theming the tool’s output than just choosing 16 ANSI colours. I don’t really use , but if I did I’d probably use to just use the ANSI colours that I have set in my normal terminal colorscheme. A bunch of people on Mastodon mentioned a specific issue with grays in the Solarized theme: when I list a directory, the base16 Solarized Light theme looks like this: but iTerm’s default Solarized Light theme looks like this: This is because in the iTerm theme (which is the original Solarized design ), colors 9-14 (the “bright blue”, “bright red”, etc) are mapped to a series of grays, and when I run , it’s trying to use those “bright” colours to color my directories and executables. My best guess for why the original Solarized theme is designed this way is to make the grays available to the vim Solarized colorscheme . I’m pretty sure I prefer the modified base16 version I use where the “bright” colours are actually colours instead of all being shades of gray though. (I didn’t actually realize the version I was using wasn’t the “original” Solarized theme until I wrote this post) In any case I really love Solarized and I’m very happy it exists so that I can use a modified version of it. If I my vim theme has a different background colour than my terminal theme, I get this ugly border, like this: This one is a pretty minor issue though and I think making your terminal background match your vim background is pretty straightforward. A few people mentioned problems with terminal applications setting an unwanted background colour, so let’s look at an example of that. Here has set the background to color #16 (“black”), but the script I use sets color 16 to be bright orange, so I get this, which is pretty bad: I think the intention is for ngrok to look something like this: I think sets color #16 to orange (instead of black) so that it can provide extra colours for use by base16-vim . This feels reasonable to me – I use in the terminal, so I guess I’m using that feature and it’s probably more important to me than (which I rarely use) behaving a bit weirdly. This particular issue is a maybe obscure clash between ngrok and my colorschem, but I think this kind of clash is pretty common when a program sets an ANSI background color that the user has remapped for some reason. A bunch of terminals (iTerm2, tabby , kitty’s text_fg_override_threshold , and folks tell me also Ghostty and Windows Terminal) have a “minimum contrast” feature that will automatically adjust colours to make sure they have enough contrast. Here’s an example from iTerm. This ngrok accident from before has pretty bad contrast, I find it pretty difficult to read: With “minimum contrast” set to 40 in iTerm, it looks like this instead: I didn’t have minimum contrast turned on before but I just turned it on today because it makes such a big difference when something goes wrong with colours in the terminal. A few people mentioned that they’ll SSH into a system that doesn’t support the environment variable that they have set locally, and then the colours won’t work. I think the way works is that systems have a database, so if the value of the environment variable isn’t in the system’s terminfo database, then it won’t know how to output colours for that terminal. I don’t know too much about terminfo, but someone linked me to this terminfo rant that talks about a few other issues with terminfo. I don’t have a system on hand to reproduce this one so I can’t say for sure how to fix it, but this stackoverflow question suggests running something like instead of . A couple of problems people mentioned with designing / finding terminal colorschemes: Another problem people mentioned is using a program like nethack or midnight commander which you might expect to have a specific colourscheme based on the default ANSI terminal colours. For example, midnight commander has a really specific classic look: But in my Solarized theme, midnight commander looks like this: The Solarized version feels like it could be disorienting if you’re very used to the “classic” look. One solution Simon Tatham mentioned to this is using some palette customization ANSI codes (like the ones base16 uses that I talked about earlier) to change the color palette right before starting the program, for example remapping yellow to a brighter yellow before starting Nethack so that the yellow characters look better. If I run , I see something like this, with the colours disabled. In general I find this useful – if I pipe a command to , I don’t want it to print out all those color escape codes, I just want the plain text. But what if you want to see the colours? To see the colours, you can run ! I just learned about recently and I think it’s really cool, opens a tty for the command to write to so that it thinks it’s writing to a TTY. It also fixes issues with programs buffering their output when writing to a pipe, which is why it’s called . Here’s what the output of looks like for me: Also some commands (including ) support a flag which will force them to always print out the colours. Some people mentioned that they don’t want to use colour at all, perhaps because uses blue, it’s hard to read on black, and maybe they don’t feel like customizing their terminal’s colourscheme to make the blue more readable or just don’t find the use of colour helpful. Some possible solutions to this one: Here’s an example of running : I used to have a lot of problems with configuring my colours in vim – I’d set up my terminal colours in a way that I thought was okay, and then I’d start vim and it would just be a disaster. I think what was going on here is that today, there are two ways to set up a vim colorscheme in the terminal: 20 years ago when I started using vim, terminals with 24-bit hex color support were a lot less common (or maybe they didn’t exist at all), and vim certainly didn’t have support for using 24-bit colour in the terminal. From some quick searching through git, it looks like vim added support for 24-bit colour in 2016 – just 8 years ago! So to get colours to work properly in vim before 2016, you needed to synchronize your terminal colorscheme and your vim colorscheme. Here’s what that looked like , the colorscheme needed to map the vim color classes like to ANSI colour numbers. But in 2024, the story is really different! Vim (and Neovim, which I use now) support 24-bit colours, and as of Neovim 0.10 (released in May 2024), the setting (which tells Vim to use 24-bit hex colours for colorschemes) is turned on by default in any terminal with 24-bit color support. So this “you need to synchronize your terminal colorscheme and your vim colorscheme” problem is not an issue anymore for me in 2024, since I don’t plan to use terminals without 24-bit color support in the future. The biggest consequence for me of this whole thing is that I don’t need base16 to set colors 16-21 to weird stuff anymore to integrate with vim – I can just use a terminal theme and a vim theme, and as long as the two themes use similar colours (so it’s not jarring for me to switch between them) there’s no problem. I think I can just remove those parts from my shell script and totally avoid the problem with ngrok and the weird orange background I talked about above. I think there are a lot of issues around the intersection of multiple programs, like using some combination tmux/ssh/vim that I couldn’t figure out how to reproduce well enough to talk about them. Also I’m sure I missed a lot of other things too. I’ve personally had a lot of success with using base16-shell with base16-vim – I just need to add a couple of lines to my fish config to set it up (+ a few lines) and then I can move on and accept any remaining problems that that doesn’t solve. I don’t think base16 is for everyone though, some limitations I’m aware of with base16 that might make it not work for you: Apparently there’s a community fork of base16 called tinted-theming , which I haven’t looked into much yet. Just one so far but I’ll link more if people tell me about them: We talked about a lot in this post and while I think learning about all these details is kind of fun if I’m in the mood to do a deep dive, I find it SO FRUSTRATING to deal with it when I just want my colours to work! Being surprised by unreadable text and having to find a workaround is just not my idea of a good day. Personally I’m a zero-configuration kind of person and it’s not that appealing to me to have to put together a lot of custom configuration just to make my colours in the terminal look acceptable. I’d much rather just have some reasonable defaults that I don’t have to change. My one big takeaway from writing this was to turn on “minimum contrast” in my terminal, I think it’s going to fix most of the occasional accidental unreadable text issues I run into and I’m pretty excited about it.
Shell
C
Tutorial
Programming
C++
CSS
Python
DevOps
Frontend
JavaScript
HTML
Web Development
Go
Performance
Ruby