img2iterm

command module
v0.0.0-...-14aafb0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 13, 2026 License: GPL-2.0 Imports: 13 Imported by: 0

README

img2iterm

img2iterm generates a terminal color scheme from an image. It extracts the dominant colors of the image, builds a complete 16-color ANSI palette (plus background, foreground, and cursor), and can either apply it to the current terminal immediately or export it as an .itermcolors file for import into iTerm2.

Table of Contents

Features

  • Supports JPEG, PNG, and HEIC images.
  • Dominant color extraction using k-means clustering.
  • Generates all 16 ANSI colors (normal and bright), plus background, foreground, cursor, and selection colors.
  • Applies the palette instantly to the current terminal session using standard escape sequences.
  • Exports to the .itermcolors format (iTerm2 property list).
  • Single binary with no runtime system dependencies.

Requirements

  • Go 1.26.1 or later (build only).
  • A terminal that supports OSC 4, 10, 11, and 12 escape sequences to apply colors directly (see Terminal Compatibility).
  • iTerm2, if you want to import the generated .itermcolors file.

Installation

go install github.com/VictorHumberto01/img2iterm@latest

The binary is installed to $(go env GOPATH)/bin (by default, ~/go/bin). Make sure that directory is in your PATH:

export PATH="$PATH:$(go env GOPATH)/bin"

Add this line to your ~/.zshrc or ~/.bashrc to make it permanent.

Building from source
git clone https://github.com/VictorHumberto01/img2iterm.git
cd img2iterm
go build -o img2iterm .

This creates the img2iterm binary in the current directory. To run it from anywhere, move it to a directory in your PATH:

sudo mv img2iterm /usr/local/bin/

Alternatively, run go install . from the repository directory to install it to $(go env GOPATH)/bin.

Uninstalling

Remove the binary from wherever it was installed:

rm "$(go env GOPATH)/bin/img2iterm"   # if installed with go install
sudo rm /usr/local/bin/img2iterm      # if moved to /usr/local/bin
Verifying the installation
img2iterm

When run without arguments, the program prints its usage message:

Usage: img2iterm -i <image_path> [-o <output_name>]

Usage

img2iterm -i <image_path> [-o <output_name>] [-a=false]

By default, img2iterm applies the generated palette to the current terminal. Colors applied this way last only for the current session and are discarded when the window or tab is closed. To keep a scheme permanently, export it as .itermcolors and import it into iTerm2.

Options

Flag Type Default Description
-i string (none) Path to the input image. Required.
-o string (none) Output file name, without extension. The .itermcolors extension is appended automatically.
-a bool true Apply the colors to the current terminal. Use -a=false to disable.

Behavior for each combination of flags:

Command Applies to terminal Writes .itermcolors
img2iterm -i photo.jpg Yes No
img2iterm -i photo.jpg -o theme Yes Yes (theme.itermcolors)
img2iterm -i photo.jpg -a=false No Yes (photo.itermcolors)
img2iterm -i photo.jpg -o theme -a=false No Yes (theme.itermcolors)

When -a=false is used without -o, the output file name is derived from the image file name.

Note: because -a is a boolean flag parsed by Go's flag package, the form -a false (with a space) does not disable it. Always use -a=false.

Examples

Apply the colors of a wallpaper to the current terminal:

img2iterm -i ~/Pictures/wallpaper.png

Apply the colors and also save the scheme as ocean.itermcolors:

img2iterm -i ~/Pictures/beach.jpg -o ocean

Only generate the file, without changing the terminal:

img2iterm -i ~/Pictures/IMG_0421.heic -a=false
# Saved to IMG_0421.itermcolors

The file is saved to the current working directory. To save it elsewhere, include a path in -o:

img2iterm -i photo.jpg -o ~/themes/photo -a=false

Importing into iTerm2

  1. Generate the .itermcolors file using -o or -a=false.
  2. Open iTerm2 and go to Settings > Profiles > Colors.
  3. Click Color Presets... and select Import....
  4. Choose the generated .itermcolors file.
  5. Open Color Presets... again and select the imported scheme.

Alternatively, opening the file directly also imports it:

open theme.itermcolors

How It Works

  1. Load and resize. The image is decoded and downscaled to 100x100 pixels (Lanczos3 filter), which speeds up analysis without meaningful loss of color information.
  2. Color extraction. k-means clustering identifies the dominant colors in the image.
  3. Sort by lightness. The extracted colors are sorted from darkest to lightest (HSL color space).
  4. Background and foreground. The darkest color becomes the background, with lightness capped at 10%. The lightest color becomes the foreground, with lightness of at least 90%.
  5. Neutral tones. Black (0) uses the background color; white (7) is derived from the foreground with lightness capped at 70%; bright black (8) is derived from the background with lightness of at least 30%; bright white (15) uses the foreground color.
  6. Chromatic colors. For each ANSI hue (red 0, yellow 60, green 120, cyan 180, blue 240, magenta 300 degrees), the tool picks the extracted color whose hue is closest to the target, favoring more saturated colors. It then adjusts it:
    • Normal variant (1 to 6): lightness between 50% and 70%, saturation of at least 50%.
    • Bright variant (9 to 14): lightness between 70% and 90%, saturation of at least 60%.
  7. Output. The palette is applied to the terminal via escape sequences and/or written as a property list in .itermcolors format. In the exported file, the cursor uses the foreground color, and the selection swaps background and foreground.

Because both normal and bright colors are derived from actual colors in the image, the result preserves the visual identity of the source while keeping enough contrast for readability.

Terminal Compatibility

Applying colors directly uses the OSC 4 (ANSI palette), OSC 10 (foreground), OSC 11 (background), and OSC 12 (cursor) escape sequences. These are supported by most modern terminal emulators, including:

  • iTerm2
  • kitty
  • WezTerm
  • Alacritty
  • GNOME Terminal and other VTE-based terminals
  • Konsole

Support in macOS Terminal.app is limited. In that case, or in any terminal without support, use -a=false to generate the file only.

Inside tmux or GNU screen, the escape sequences may be intercepted by the multiplexer and never reach the terminal. Run the command outside the multiplexer, or enable passthrough (for example, set -g allow-passthrough on in tmux).

Troubleshooting

Error decoding image: image: unknown format The image format is not supported. Convert it to JPEG, PNG, or HEIC.

Error opening image: ... no such file or directory Check the path passed to -i. Paths containing spaces must be quoted.

The terminal colors did not change The terminal most likely does not support the OSC sequences used, or the command is running inside a multiplexer. See Terminal Compatibility.

No .itermcolors file was created With the default options, no file is written. Pass -o <name> or use -a=false.

Restoring the original terminal colors Applied colors only last for the current session. Open a new tab or window, or run reset (results vary by terminal).

License

This project is licensed under the GNU General Public License v2.0. See the LICENSE file for details.

Documentation

The Go Gopher

There is no documentation for this package.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL