A Python module for automatically rotating website favicons based on configurable time intervals. Perfect for adding dynamic visual elements to your web applications without any external API dependencies.
- Time-based favicon rotation (1 hour, 1 day, custom intervals)
- Multiple favicon sources:
- Unicode emojis
- Twemoji (Twitter's emoji set)
- Geometric icons (circles, squares, triangles, diamonds, stars)
- Curated SVG icon set rendered to crisp PNG/ICO via cairosvg
- Standalone
favicon.svgoutput for modern browsers, with.icofallback
- No API keys required - works offline with automatic fallback to geometric icons
- Robust error handling - never breaks your website
- Simple integration - just a few lines of code
- Automatic ICO generation with multiple sizes (16x16, 32x32, 48x48)
- Generates multi-size ICO files (16x16, 32x32, 48x48)
pip install dynamic-faviconTo enable SVG rasterization (recommended), install with the svg extra. This pulls in cairosvg, which requires the system cairo library.
pip install "dynamic-favicon[svg]"If cairosvg is unavailable, the rotator still works and falls back to a simple PIL renderer.
from dynamic_favicon import FaviconRotator, FaviconScheduler
# Initialize the favicon rotator
rotator = FaviconRotator(output_dir="static", favicon_name="favicon.ico")
# Create a favicon from an emoji
rotator.create_emoji_favicon("🚀")
# Or create a random geometric icon
rotator.create_icon_favicon()
# Create a specific SVG icon with color
rotator.create_icon_favicon(name="bolt", color="#f59e0b")
# Write standalone SVG favicon
rotator.create_svg_favicon(name="hexagon", color="#6366f1")from dynamic_favicon import FaviconRotator, FaviconScheduler
# Setup favicon rotation
rotator = FaviconRotator(output_dir="static")
scheduler = FaviconScheduler(rotator)
# Rotate emoji favicons every hour
scheduler.schedule_rotation(interval="1hour", rotation_type="emoji", category="nature")
# Start the scheduler (runs in background)
scheduler.start()
# Your web server code here...
# The favicon will automatically update every hour
# Stop when needed
scheduler.stop()from flask import Flask
from dynamic_favicon import FaviconRotator, FaviconScheduler
app = Flask(__name__)
# Setup favicon rotation
rotator = FaviconRotator(output_dir="static")
scheduler = FaviconScheduler(rotator)
# Rotate every 30 minutes with random icons
scheduler.schedule_rotation(interval="30min", rotation_type="icon")
scheduler.start()
@app.route('/')
def home():
return '<html><head><link rel="icon" href="/static/favicon.svg" type="image/svg+xml"><link rel="alternate icon" href="/static/favicon.ico"></head><body><h1>Dynamic Favicon Demo</h1></body></html>'
if __name__ == '__main__':
app.run()Main class for creating and managing favicons.
FaviconRotator(output_dir="static", favicon_name="favicon.ico")Methods:
create_emoji_favicon(emoji, size=32)- Create favicon from emoji (uses Twemoji)create_icon_favicon(size=32, name=None, color=None)- Create random geometric/SVG icon favicon, writes bothfavicon.icoandfavicon.svgcreate_svg_favicon(name=None, color=None)- Write onlyfavicon.svgcreate_custom_favicon(image_path, size=32)- Create favicon from any local image (PNG, JPG, etc.)rotate_emoji_favicon(category=None)- Rotate to random emojirotate_icon_favicon()- Rotate to random iconget_favicon_data_url()- Get base64 data URL of current faviconget_current_favicon_path()- Get path to current faviconcleanup()- Remove generated favicon files
Handles automatic favicon rotation on time intervals.
FaviconScheduler(favicon_rotator)Methods:
schedule_rotation(interval, rotation_type, category=None, run_immediately=True)- Setup rotation schedule (triggers immediate rotation)start()/stop()/is_running()- Control schedulerclear_schedule()- Remove all scheduled rotationsget_next_run_time()- Get datetime of next rotation
Intervals:
"1hour"or"hourly"- Every hour"1day"or"daily"- Every day"30min"- Every 30 minutes"15min"- Every 15 minutes"5min"- Every 5 minutes"10s","30s", etc. - Custom seconds (append 's')- Integer < 60 - Seconds interval
- Integer >= 60 - Minutes interval
Rotation Types:
"emoji"- Use emoji favicons"icon"- Use geometric/SVG icons
Emoji Categories:
"nature"- Nature emojis (🌟, 🌙, ☀️, etc.)"objects"- Object emojis (⚽, 🎮, 📱, etc.)"faces"- Face emojis (😊, 😎, 🤔, etc.)"symbols"- Symbol emojis (❤️, ⭐, 💎, etc.)None- Random from all categories
Available via dynamic_favicon.SVG_ICONS:
circle, ring, square, triangle, diamond, hexagon, star, heart, bolt, droplet, leaf, moon, spark, compass, shield, cube.
Default palette is exposed as dynamic_favicon.PALETTE.
rotator = FaviconRotator()
rotator.create_custom_favicon("path/to/your/image.png")scheduler = FaviconScheduler(rotator)
# Nature emojis every hour
scheduler.schedule_rotation("1hour", "emoji", "nature")
# Geometric icons every 30 minutes
scheduler.schedule_rotation("30min", "icon")
scheduler.start()data_url = rotator.get_favicon_data_url()
# Returns: "data:image/x-icon;base64,AAABAAEAEBAAAAEAIABoBAAAFgAAA..."
# Use in HTML
html = f'<link rel="icon" href="{data_url}">'The module is designed with robust error handling to ensure your website never breaks:
- All methods return
True/Falseto indicate success - Failed favicon creation falls back gracefully
- Network errors (for Twemoji) don't crash the application
- Scheduler continues running even if individual rotations fail
if not rotator.create_emoji_favicon("🚀"):
# Fallback to geometric icon
rotator.create_icon_favicon()- Python 3.8+
- Pillow (PIL) for image processing
- requests for fetching Twemoji images
- schedule for time-based automation
- cairosvg (optional, for SVG rasterization; requires the system
cairolibrary)
python -m buildpip install twine
twine upload dist/*pip install dynamic-faviconFork the repository Create a feature branch Make your changes Add tests Submit a pull request
For issues and questions:
- Create an issue on GitHub
- Check existing documentation
- Review the examples above
Methods:
schedule_rotation(interval, rotation_type, category=None, run_immediately=True)start()/stop()/is_running()clear_schedule()get_next_run_time()
Intervals: "1hour", "hourly", "1day", "daily", "30min", "10s", integers (seconds when < 60, minutes otherwise).
Rotation types: "emoji", "icon".
Emoji categories: "nature", "objects", "faces", "symbols", or None for any.
Available via dynamic_favicon.SVG_ICONS:
circle, ring, square, triangle, diamond, hexagon, star, heart, bolt, droplet, leaf, moon, spark, compass, shield, cube.
Default palette is exposed as dynamic_favicon.PALETTE.
Every public method returns a boolean and swallows internal failures so the host application stays up. Network failures fetching Twemoji fall back to a bundled SVG icon. If cairosvg is missing or the C library is not present, a simple PIL renderer is used instead.
PIL/Pillow: Core image processing library for resizing rasterized SVGs and writing multi-size ICO files.
cairosvg (optional): Rasterizes bundled SVG icons to PNG bytes for high-quality favicon generation. Requires the system cairo library. The module degrades gracefully to a simple PIL fallback when unavailable.
requests: HTTP client for fetching Twemoji images from Twitter's CDN. Includes timeout handling and error management for network requests.
schedule: Task scheduling library that manages time-based favicon rotations. Provides flexible interval configuration and thread-safe execution.
threading: Python standard library used to run the scheduler in background threads, preventing blocking of the main application.
Twemoji CDN: External service providing high-quality emoji images via HTTP requests. System gracefully handles API unavailability by falling back to local geometric icon generation.
Note
The module is designed to work offline when external services are unavailable, ensuring reliability in various deployment environments.