Dynamic Favicon
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.
Features
- 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)
Installation
pip install dynamic-favicon
To 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.
Quick Start
Basic Usage
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")
Automated Rotation
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()
Flask Integration
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()
API Reference
FaviconRotator
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
FaviconScheduler
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
Bundled SVG icons
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.
Advanced Usage
Custom Favicon from Image
rotator = FaviconRotator()
rotator.create_custom_favicon("path/to/your/image.png")
Multiple Scheduled Rotations
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()
Get Favicon as Data URL
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}">'
Error Handling
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
Safe error handling example
if not rotator.create_emoji_favicon("🚀"):
# Fallback to geometric icon
rotator.create_icon_favicon()
Requirements
- 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)
Publishing to PyPI
Build the Package
python -m build
Upload to PyPI
pip install twine
twine upload dist/*
Test Installation
pip install dynamic-favicon
Contributing
Fork the repository Create a feature branch Make your changes Add tests Submit a pull request
Support
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.
Bundled SVG icons
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.
Error Handling
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.
External Dependencies
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.
Metadata
Release files for dynamic-favicon 1.1.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| dynamic_favicon-1.1.0.tar.gz | 13.5 kB | Without provenance | Details for dynamic_favicon-1.1.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| dynamic_favicon-1.1.0-py3-none-any.whl | Python 3 | none | any | Details for dynamic_favicon-1.1.0-py3-none-any.whl |
Total release size: 24.7 kB
Release files / dynamic_favicon-1.1.0.tar.gz
| Download URL | dynamic_favicon-1.1.0.tar.gz |
|---|---|
| Size | 13.5 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
2c99830f7ee63a3cfda2845bf1e93d7e6128ba9f54024143bc021ccb864a2440
|
|
BLAKE2b-256 checksum How to use checksums |
d35b49881e5b5fb9ea0c38ab3525bb3430e34fb4dd3f02dbdd4d722713251a41
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.12.1
|
Release files / dynamic_favicon-1.1.0-py3-none-any.whl
| Download URL | dynamic_favicon-1.1.0-py3-none-any.whl |
|---|---|
| Size | 11.2 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
eeee72d4510b88c7321b147a8d72aebc1cd8d48a1c7bf1921d364e91d3d8fb53
|
|
BLAKE2b-256 checksum How to use checksums |
30ddc96d54dce29879e66689b646e2da470eaac9a32ef00a643b13be0c8364e8
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.12.1
|
Security for dynamic-favicon 1.1.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.