icon-gen-ai

Generate pixel-perfect icons from Iconify, direct URLs, and local files—with animation support and exports to PNG, SVG, WebP, and ICO.

_{Read the Documentation • Try the Interactive Playground}

Features

AI-assisted icon search and generation
Simple and intuitive CLI and Python API
Access 275,000+ icons from Iconify
Unlimited icons from direct URLs or local files
Customize colors, sizes, and backgrounds and adjust border radius
Gradient color option for icons and backgrounds
Export to SVG, PNG, WEBP, or ICO format

Tech Stack

Backend

• Python 3.10+ — package language
• Current support for LLMs from Anthropic and OpenAI directly or via Hugging Face

Playground

• React — interactive frontend
• Vite — fast dev server and production bundler
• Tailwind CSS — utility-first styling
• Javascript — component and API code

CLI

• Click — Python package for creating beautiful command line interfaces in a composable way

Packaging

• PyPI — distributed as an installable Python package

Installation

pip install icon-gen-ai

(Optional) AI features:

pip install icon-gen-ai[ai]

After installing AI features, configure at least one API key:

• OpenAI: Set OPENAI_API_KEY environment variable
• Anthropic: Set ANTHROPIC_API_KEY environment variable
• Hugging Face: Set HF_TOKEN environment variable

Check provider status:

icon-gen-ai providers

Quick Start

Generate Single Icons

from icon_gen_ai import IconGenerator

generator = IconGenerator(output_dir="output")

# From URL
generator.generate_icon(
    direct_url='https://upload.wikimedia.org/wikipedia/commons/b/b0/Claude_AI_symbol.svg',
    output_name='claude_white_mediumslateblue_bg',
    color='white',
    bg_color='mediumslateblue',
    border_radius=0,
    size=256
)

# From Iconify
generator.generate_icon(
    icon_name='simple-icons:googlegemini',
    output_name='gemini_white_deeppink_bg',
    color='white',
    bg_color='deeppink',
    border_radius=128,  # Circle (half of size)
    size=256
)

# From Iconify 
generator.generate_icon(
    icon_name='simple-icons:mistralai',
    output_name='mistral_white_gradient_bg',
    color='white',
    bg_color=('mediumslateblue', 'deeppink'),  # Gradient
    direction="vertical",
    border_radius=48,
    size=256
)

# From Iconify 
generator.generate_icon(
    icon_name='simple-icons:openai',
    output_name='openai_gradient_transparent_bg',
    color=('mediumslateblue', 'deeppink'),  # Gradient icon
    direction="diagonal",
    bg_color=None,
    size=256
)

Generate Multiple Icons (Batch)

from icon_gen_ai import IconGenerator

generator = IconGenerator(output_dir="output")

# Generate multiple icons at once
ai_icons = {
    'llama_deepskyblue': 'simple-icons:meta',
    'deepseek_deepskyblue': {
        'local_file': 'input/deepseek-icon.png'
    },
    'nemotron_deepskyblue': {
        'url': 'https://companieslogo.com/img/orig/NVDA-df4c2377.svg'
    },
    'grok_deepskyblue': {
        'url': 'https://unpkg.com/@lobehub/icons-static-svg@latest/icons/grok.svg'
    }
}

generator.generate_batch(ai_icons, color='deepskyblue', size=256, outline_color='deepskyblue', outline_width=8, border_radius=48)

Create Custom Animations

You can add four types of animations to the SVG icons: spin, pulse, flip horizontally, and flip vertically.

from icon_gen_ai import IconGenerator

generator = IconGenerator(output_dir="output")

icons_with_custom_ani = {
    f'disk': {'icon':'qlementine-icons:disk-16',"animation":"spin:4s"},
    f'cicle': {'icon':'clarity:dot-circle-line',"animation":"pulse:1s"},
    f'coffee': {'icon':'gg:coffee',"animation":"flip-h:1s"},
    f'card': {'icon':'famicons:card-outline',"animation":"flip-v:1s"},
}

generated = generator.generate_batch(
    icons_with_custom_ani, 
    color='white', 
    size=256,  
    bg_color=('deeppink','mediumslateblue'), 
    border_radius=48)

Support for Embedded Animations

When you apply a solid color to an animated SVG icon, the animations are automatically preserved:

from icon_gen_ai import IconGenerator

generator = IconGenerator(output_dir="output")

color = 'mediumslateblue' 

animated_icons = {
    f'ani_embedded_blocks': 'svg-spinners:blocks-wave',
    f'ani_embedded_upload': 'line-md:upload-outline-loop',
    f'ani_embedded_location': 'line-md:my-location-loop',
    f'ani_embedded_bars': 'svg-spinners:bars-scale-middle'
}

generator.generate_batch(animated_icons, color=color, size=256, outline_color='springgreen', bg_color='snow', outline_width=8, border_radius=48)

What preserves animations:

• Solid colors
• No color specified (original colors)
• Backgrounds and outlines

What removes animations:

• Gradient colors on the icon itself: color=('deeppink', 'mediumslateblue')

Note: Background gradients don't affect icon animations - only icon color gradients do.

CLI Usage

Below is the full output of icon-gen-ai --help:

Usage: icon-gen-ai [OPTIONS] COMMAND [ARGS]...

  icon-gen-ai — generate icons from Iconify, URLs, or local files.

Options:
  --version  Show the version and exit.
  --help     Show this message and exit.

Commands:
  generate   Generate icons from Iconify or local files.
  providers  Show AI provider status.
  search     Search for icons using natural language queries.

Read the documentation for more detailed instructions.

Icon Sources

Three ways to get icons:

1. Iconify (275,000+ icons)

Browse at Iconify

# Format: collection:icon-name
'simple-icons:openai'           # Simple Icons by Simple Icons Collaborators (License: CC0 1.0)  
'mdi:github'                    # Material Design Icons by Pictogrammers (License: Apache 2.0)  
'devicon:fastapi'               # Devicon by konpa (License: MIT)  
'gis:drone'                     # Font-GIS by Jean-Marc Viglino (License: CC BY 4.0)  

AI-powered search (requires pip install icon-gen-ai[ai]):

icon-gen-ai search "payment icons for checkout"

2. Direct URL

Any public image URL:

direct_url='https://upload.wikimedia.org/wikipedia/commons/b/b0/Claude_AI_symbol.svg'
direct_url='https://companieslogo.com/img/orig/NVDA-df4c2377.svg'

3. Local File

Locally saved images:

local_file='input/pypi-icon.svg'
local_file='input/github-mark.png'
local_file='input/html_css_js-icon.jpeg'
local_file='input/react-icon.webp'

Examples

Check out the examples/ directory for more use cases:

Basic Generation:

• generate_ai_icons_singular.py - Generate icons one-by-one with custom backgrounds & gradients
• generate_ai_icons_batch.py - Generate multiple AI model icons at once (batch mode)

AI-Powered Search (requires pip install icon-gen-ai[ai]):

• ai_simple_usage.py - Search and generate icons using natural language
• ai_icon_search.py - Advanced search with custom styles and project context

Development

# Clone the repository
git clone https://github.com/yauheniya-ai/icon-gen-ai.git
cd icon-gen-ai

# Install all dependencies (including dev tools)
uv sync --extra ai --dev

# Run tests
uv run pytest --cov=src --cov-report=term-missing

License

MIT License – see LICENSE file for details.

Contributing

Contributions are welcome!

1. Fork the repository
2. Create a feature branch (git checkout -b feature/my-change) and make your changes
3. Run the test suite: pytest --cov=src --cov-report=term-missing
4. Format and lint: ruff format src/ tests/ && ruff check src/ tests/
5. Update the documentation
6. Submit a pull request