or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

index.md
tile.json

tessl/pypi-pygifsicle

Python package wrapping the gifsicle library for editing and optimizing gifs

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
pypipkg:pypi/pygifsicle@1.1.x

To install, run

npx @tessl/cli install tessl/pypi-pygifsicle@1.1.0

index.mddocs/

Pygifsicle

Python package wrapping the gifsicle library for editing and optimizing GIF images. Provides a simple Python interface to the powerful gifsicle command-line tool, enabling GIF optimization and manipulation from Python scripts.

Package Information

  • Package Name: pygifsicle
  • Package Type: pypi
  • Language: Python
  • Installation: pip install pygifsicle
  • External Dependency: gifsicle binary (automatically installed on macOS via brew)

Core Imports

from pygifsicle import gifsicle, optimize

Basic Usage

from pygifsicle import optimize

# Simple optimization - overwrites original file
optimize("my_animation.gif")

# Optimization with destination file
optimize("source.gif", "optimized.gif")

# Using pathlib Path objects
from pathlib import Path
source_path = Path("animations/big_file.gif")
dest_path = Path("animations/small_file.gif")
optimize(source_path, dest_path)

Capabilities

GIF Optimization

Optimizes GIF files using gifsicle with the --optimize flag enabled. This is the most common use case for reducing GIF file sizes while maintaining visual quality.

def optimize(source: Union[str, Path], destination: Optional[str] = None, **kwargs) -> None:
    """
    Optimize given gif using gifsicle with optimize flag enabled.

    Parameters:
    - source: Union[str, Path] - Path to gif image to optimize
    - destination: Optional[str] - Output path (defaults to overwrite source)
    - **kwargs - Additional arguments passed to gifsicle function (colors, options)

    Raises:
    - ValueError: If source path doesn't exist or is not a gif file
    - FileNotFoundError: If gifsicle binary is not found on system
    """

General GIF Processing

Provides full access to gifsicle functionality with customizable options, colors, and processing parameters. Supports single files, multiple files, and file merging operations.

def gifsicle(
    sources: Union[List[str], str, List[Path], Path],
    destination: Optional[str] = None,
    optimize: bool = False,
    colors: int = 256,
    options: Optional[List[str]] = None,
) -> None:
    """
    Apply gifsicle with given options to image at given paths.

    Parameters:
    - sources: Union[List[str], str, List[Path], Path] - Path or paths to gif(s) to process
    - destination: Optional[str] - Output path (defaults to overwrite first source)
    - optimize: bool - Whether to add optimize flag (default: False)
    - colors: int - Number of colors to use, must be power of 2 (default: 256)
    - options: Optional[List[str]] - Additional gifsicle command-line options

    Raises:
    - ValueError: If source path doesn't exist, source is not a gif, or destination is not a gif
    - FileNotFoundError: If gifsicle binary is not found on system
    """

Usage Examples

Single File Optimization

from pygifsicle import optimize

# Optimize in place
optimize("animation.gif")

# Optimize to new file
optimize("large_animation.gif", "small_animation.gif")

Advanced Processing with Custom Options

from pygifsicle import gifsicle

# Merge multiple GIFs into one optimized file
gifsicle(
    sources=["part1.gif", "part2.gif", "part3.gif"],
    destination="merged.gif",
    optimize=True,
    colors=128,
    options=["--verbose"]
)

# Process with custom color reduction
gifsicle(
    sources="input.gif",
    destination="output.gif",
    colors=64,
    options=["--lossy=80"]
)

Using Path Objects

from pygifsicle import optimize, gifsicle
from pathlib import Path

# With Path objects
input_file = Path("animations/source.gif")
output_file = Path("animations/optimized.gif")

optimize(input_file, output_file)

# Multiple Path objects
sources = [Path("gif1.gif"), Path("gif2.gif")]
gifsicle(sources, destination="combined.gif", optimize=True)

Types

from typing import Union, List, Optional
from pathlib import Path

# Core types used in the API
str = str  # Built-in string type
Path = pathlib.Path  # pathlib Path objects for file paths
Union[str, Path] = Union[str, Path]  # Either string or Path object
List[str] = List[str]  # List of strings
Optional[str] = Optional[str]  # Optional string parameter

Error Handling

ValueError

Raised when:

  • Source file path does not exist
  • Source file is not a GIF image (doesn't end with .gif)
  • Destination path is not a GIF image

FileNotFoundError

Raised when the gifsicle binary is not found on the system. The error message includes installation instructions:

  • macOS: Automatically installed via brew during pip install
  • Linux: Install via sudo apt-get install gifsicle (Ubuntu/Debian) or equivalent
  • Windows: Download from https://eternallybored.org/misc/gifsicle/

Installation Requirements

Python Dependencies

  • Python 3.x
  • Standard library only (typing, subprocess, os, pathlib)

System Dependencies

  • gifsicle binary: Must be installed and available in system PATH
  • Installation is automatically attempted on macOS via brew
  • Manual installation required on Linux and Windows (instructions provided during pip install)

Common Patterns

Batch Processing

from pygifsicle import optimize
import os

# Optimize all GIFs in a directory
gif_dir = "animations/"
for filename in os.listdir(gif_dir):
    if filename.endswith(".gif"):
        filepath = os.path.join(gif_dir, filename)
        optimize(filepath)

Error Handling

from pygifsicle import optimize

try:
    optimize("animation.gif")
except FileNotFoundError:
    print("gifsicle not installed. Please install gifsicle binary.")
except ValueError as e:
    print(f"Invalid file: {e}")