gif-color-changer 0.2.0

Replace colors across every frame of a GIF from the command line.

GIF Color Changer

Command line tool for replacing colors across every frame of a GIF.

Install

uv tool install gif-color-changer

From a local checkout:

uv tool install .

Usage

gifcc input.gif output.gif \
  --map "#FFFFFF=#FF0000" \
  --map "#000000=#00FF00"

Each --map is:

source_color=replacement_color

So this:

--map "#FFFFFF=#FF0000"

means:

replace white with red

You can pass as many mappings as you need. They run in order, and a pixel is only changed once.

Tolerance

GIF colors are often not exactly what they look like, especially after palette conversion or compression. Use --tolerance to match colors that are close to the source color.

gifcc input.gif output.gif \
  --map "#FFFFFF=#FF0000" \
  --tolerance 20

The default tolerance is 10.

Output

The script prints how many pixels were changed for each mapping:

(255, 255, 255) -> (255, 0, 0): changed 1234 pixel(s)

If a mapping says it changed 0 pixels, the source color probably does not exist in the GIF at that tolerance.

Uninstall

uv tool uninstall gif-color-changer

Development

Set up the repo:

uv sync

Run tests:

uv run pytest

Run tests against a specific Python version:

uv run --python 3.11 pytest

Or use the Makefile:

make test
make test-all
make test-3.11

Run the command without installing it as a tool:

uv run gifcc input.gif output.gif \
  --map "#FFFFFF=#FF0000"

You can also run the compatibility wrapper directly:

uv run python main.py input.gif output.gif \
  --map "#FFFFFF=#FF0000"

Build

uv build

That writes the package artifacts to dist/.