# seebi/dircolors-solarized: Solarized themes for GNU ls

> A set of dircolors themes that map the Solarized palette onto GNU ls output. The 256dark theme is the low-effort path; the ansi-* themes trade setup work for exact colors.

**seebi/dircolors-solarized** — This is a repository of themes for GNU ls (configured via GNU dircolors) that support Ethan Schoonover’s Solarized color scheme.

- Repository: https://github.com/seebi/dircolors-solarized
- Website: http://ethanschoonover.com/solarized
- Stars: 2,862 · Forks: 443
- Language: Makefile
- License: MIT
- Published: 2026-09-28 · Updated: 2026-09-28 · Language: en
- Canonical page: https://hysenlabs.com/projects/seebi-dircolors-solarized

## What dircolors-solarized actually changes

GNU ls does not decide its own colors. It reads a database of file-type to color mappings that dircolors produces, normally loaded from a shell startup file. The default database is tuned for the 16 ANSI colors and looks wrong against a Solarized background: directories and executables land on hues that clash with the palette or fall below readable contrast.

This repository is that database, rewritten for Solarized. It is not a terminal emulator theme, not a prompt, and not a plugin. It ships one file per variant, named dircolors.256dark, dircolors.256dark.no-bold, dircolors.ansi-dark, dircolors.ansi-light and dircolors.ansi-universal, plus a test-directory.tar.bz2 used to preview the result.

The audience is narrow and specific: people who run GNU ls on Linux or BSD, who have already applied Solarized to their terminal emulator, and who want ls output to sit inside that palette instead of fighting it. If your terminal is not Solarized, the 256dark theme still works, but the point of matching the palette is lost.

## Why there are two theme families instead of one

The README is explicit that "256 colors" does not necessarily mean better than "ANSI", and the split between the two families is the most interesting design decision in the repository.

The 256dark theme assumes a terminal that supports 256 colors. It approximates the Solarized palette using extended color codes, which means it needs no terminal reconfiguration at all: you point dircolors at the file and you are done. The cost is that the colors are approximate. The README notes that a future .Xresources could remap the 256-color slots to the exact Solarized palette, and that work "has not yet started", so today the approximation stands.

The ansi-* themes take the opposite trade. They emit the 16 base ANSI codes, so the terminal itself must be configured to display Solarized in those 16 slots. That yields the exact palette but caps you at 16 colors. The variants differ in emphasis: ansi-universal is designed to stay readable across four palettes (Solarized Dark, Solarized Light, and default ANSI colors on both dark and light backgrounds), while ansi-dark and ansi-light are tuned for one Solarized variant at the slight expense of the other.

That fallback design is worth calling out. The README states the universal theme was built so that on a terminal where Solarized has not been set up, elements do not become "invisible, incrediby hard to read, or a boring gray". Anyone who SSHes into machines with different terminal configurations will care about that more than about exactness.

## Installing a theme and previewing it with the test directory

The README's Installation section is the place to look for the canonical steps; the repository itself contains the theme files at the top level and a Makefile with a single target. The Makefile target unpacks test-directory.tar.bz2 and then applies a chain of permissions and special bits so the preview exercises the interesting cases.

```bash
make prepare-directory
```

After that runs, a test-directory appears in the repository root containing hardlinks, a setgid file, a setuid file, a world-writable directory, a directory with the sticky bit, and files with the read-only and executable bits set. Run ls inside it with your chosen theme loaded and you can see how each class is colored.

The repository does not document how to load a theme into your shell; it points to the Installation section of the README for that. The theme files themselves are dircolors databases, so the mechanism is the one dircolors already provides. Put the loading line in your shell startup file to make it permanent. The 256dark.no-bold variant exists for terminals where bold text is rendered as a brighter color rather than a heavier weight, which changes what the bold hierarchies in the theme look like.

The README also points to an "Angry Flashing Tab Complete Fix" section. That is a known annoyance with colored completion output, and the README treats it as a separate concern from the theme files themselves.

## The macOS case is a dead end with the system ls

The README opens with a blunt warning: on macOS the system ls is not GNU ls, so these themes cannot be used. That is a hard limitation, not a configuration problem. The README points to a community workaround in issue 10 and notes that another option is installing GNU ls through homebrew coreutils. If you install coreutils, you are no longer using the ls that ships with the OS, and the dircolors command comes along with it.

This is the clearest case where the project is the wrong tool. A macOS user who wants colored ls output without replacing the system binary should look at the workaround thread instead of the theme files. The repository does not attempt to support BSD ls or any ls that ignores LS_COLORS.

A second, quieter limitation: the 256dark theme's approximation means the colors you see are not the Solarized hex values. If exact palette fidelity is the reason you are here, the ansi-* themes are the only path, and they require the terminal-side work the README describes.

## How this differs from a terminal emulator Solarized port

The obvious alternative is the Solarized repository itself, altercation/solarized, which the README lists as the main repository. It ships color scheme implementations for terminal emulators, editors and other applications. Applying its iTerm2 or GNOME Terminal profile changes the 16 ANSI colors your terminal displays, but it does not change which of those colors ls assigns to a directory, a symlink or an executable. You still get the default dircolors mapping, just rendered in Solarized hues.

The difference in approach matters. The emulator port defines what color index 4 looks like; this repository defines which index a given file type gets. They are complementary, and the ansi-* themes only make sense once the emulator port is in place. The 256dark theme deliberately avoids depending on the emulator port, which is why it is the easier of the two to adopt and the less exact.

If you want Solarized everywhere with no per-tool configuration, the emulator port alone gets you most of the way. If ls output is the part that bothers you, this repository is the piece the emulator port does not cover.

## Maintenance, licensing and what upgrading costs

The repository is not archived, and the last push was on 2026-05-27. The theme files are plain text color databases, so there is no build step, no dependency graph and no runtime. Upgrading means replacing one file and reloading it. There is no migration path to plan because there is no state.

The practical maintenance question is whether your terminal setup changes, not whether the repository does. If you later switch from a 256-color terminal to one where you have configured the exact Solarized ANSI palette, you would move from dircolors.256dark to one of the ansi-* files, and the preview workflow with make prepare-directory is the way to check the result before committing to it.

Licensing is MIT, per the LICENSE file at the repository root. That is permissive and imposes essentially no obligation beyond retaining the notice, but the theme files embed color choices derived from the Solarized palette, and the README links to the Solarized homepage rather than restating its terms. If you plan to redistribute the theme files inside a product, read both licenses rather than assuming MIT covers everything in the directory. This is not legal advice.

## Conclusion

Adopt it if you already run GNU ls and a Solarized terminal, and pick 256dark unless you are willing to reconfigure your terminal's 16 ANSI colors for the exact palette. Skip it on macOS with the system ls, which is not GNU ls. Before committing, run the Makefile's prepare-directory target and check that symlinks, setuid files and directories with the sticky bit all render distinctly in your terminal.

## FAQ

### What are solarized colors?

Solarized is Ethan Schoonover's color scheme, which this repository implements for GNU ls through dircolors themes. The README links to the Solarized homepage for screenshots, details and implementations for terminal emulators, Vim, Emacs and Mutt.

### What are the hex codes for the solarized color?

The README does not list hex values; it points to the Solarized homepage for the palette itself. The 256dark theme only approximates those colors, and the ansi-* themes rely on the terminal emulator being configured to display the exact palette in its 16 ANSI slots.

### Does dircolors-solarized work with the ls that ships with macOS?

No. The README states that macOS does not use GNU ls, so these themes cannot be used there, and it points to a community workaround in issue 10 or to installing GNU ls via homebrew coreutils as alternatives.

### Which dircolors-solarized theme should I start with?

dircolors.256dark needs no terminal reconfiguration and works on any 256-color terminal, at the cost of approximating the palette. The ansi-* themes give the exact Solarized colors but require the terminal emulator's ANSI colors to be reconfigured and limit you to the 16 Solarized colors.

### How do I check what dircolors-solarized will look like before enabling it?

Run make prepare-directory, which unpacks test-directory.tar.bz2 and sets up hardlinks, setuid and setgid files, a sticky-bit directory and other special cases. Then load a theme with dircolors and run ls inside that directory to compare variants.

## Sources

- [Issues](https://github.com/seebi/dircolors-solarized/issues)
- [License: MIT](https://github.com/seebi/dircolors-solarized/blob/master/LICENSE)
- [Project website](http://ethanschoonover.com/solarized)
- [README](https://github.com/seebi/dircolors-solarized/blob/master/README.md)
- [seebi/dircolors-solarized on GitHub](https://github.com/seebi/dircolors-solarized)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/seebi-dircolors-solarized