svg2gifpy (svg2gif) 🎨➡️🎬
A high-performance CLI tool & Python library for converting animated SVG files into optimized, looping animated GIFs using headless Playwright and Pillow.
PyPI Package:
svg2gifpy(provides bothsvg2gifandsvg2gifpyCLI and Python module imports)
✨ Features
- Headless Browser Rendering: Accurate rendering of CSS animations, SMIL, and JavaScript-driven SVG animations using Playwright (Chromium).
- Aspect Ratio Preservation: Automatically detects SVG viewBox/dimensions to maintain precise aspect ratios during frame capture.
- Smart Optimization Engine:
- Downscaling: Automatically resizes large SVGs to ideal max-width parameters for smaller file outputs.
- Palette Quantization: Applies 256-color adaptive palette conversion per frame.
- Frame Compression: Leverages Pillow's optimization to discard redundant frame data.
- Max File Size Targeting (
-s): Automatically chooses the ideal balanced (FPS, duration) pair to maximize quality within a target file size. - CLI & Module Support: Installable via
pip install svg2gifpyand runnable directly from the command line (svg2giforsvg2gifpy).
👥 Guides by Audience
📖 For Users
1. Installation
Install svg2gifpy from PyPI and ensure the Playwright Chromium browser binary is installed:
pip install svg2gifpy
playwright install chromium
2. Command Line Interface (CLI)
Use the CLI binary (svg2gif or svg2gifpy) to convert SVG files from your terminal:
# Basic conversion (svg2gif and svg2gifpy commands are both available)
svg2gif -i path/to/input.svg -o path/to/output.gif
CLI Reference
usage: svg2gif [-h] [-i INPUT] [-o OUTPUT] [-d DURATION] [-f FPS]
[-w MAX_WIDTH] [-s MAX_FILE_SIZE]
Convert animated SVG files into optimized looping animated GIFs.
options:
-h, --help show this help message and exit
-i, --input INPUT Path to input .svg file (default: assets/banner.svg)
-o, --output OUTPUT Path to output .gif file (default: assets/social-preview.gif)
-d, --duration DURATION
Duration of the animation capture loop in seconds (default: 3.0).
Ignored if -s / --max-file-size is specified.
-f, --fps FPS Frames per second (default: 30).
Ignored if -s / --max-file-size is specified.
-w, --max-width MAX_WIDTH
Maximum width for output GIF downscaling (default: 640)
-s, --max-file-size MAX_FILE_SIZE, --max-size MAX_FILE_SIZE
Maximum output GIF file size in MB (e.g. 1.2 or 1.2MB, 800KB).
When set, overrides and ignores --fps and --duration to automatically
calculate the optimal balanced (fps, duration) pair within this limit.
CLI Examples
-
Custom loop duration and frame rate:
svg2gif -i banner.svg -o banner.gif -d 4.0 -f 20 -w 800
-
Constrain to maximum file size (auto-calculates optimal FPS and duration):
# Max 1.2 MB output (automatically finds highest permissible frames with balanced FPS and loop duration) svg2gif -i banner.svg -o banner.gif -s 1.2 # Using KB units svg2gif -i banner.svg -o banner.gif -s 800KB
3. Python API
Import svg2gif (or svg2gifpy) into your Python applications:
from svg2gif import convert_animated_svg_to_gif
# Alternatively: from svg2gifpy import convert_animated_svg_to_gif
# Basic conversion with explicit duration and FPS
convert_animated_svg_to_gif(
svg_path="banner.svg",
output_gif_path="banner.gif",
duration_seconds=3.0, # Duration in seconds
fps=30, # Frames per second
max_width=640 # Downscale width if original exceeds 640px
)
# Auto-optimized conversion constrained by maximum file size
convert_animated_svg_to_gif(
svg_path="banner.svg",
output_gif_path="banner.gif",
max_file_size=1.2, # Target limit in MB (e.g. 1.2 or '800KB')
max_width=640
)
💻 For Developers & Contributors
1. Clone Repository
git clone https://github.com/ishandutta2007/svg2gif.git
cd svg2gif
2. Set Up Virtual Environment
Standard venv:
python -m venv venv
# On Windows:
venv\Scripts\activate
# On Linux/macOS:
source venv/bin/activate
Or with pyenv:
pyenv install 3.11.4
pyenv virtualenv 3.11.4 svg2gif-env
pyenv local svg2gif-env
3. Install in Editable Mode
Install dependencies and link the package locally so edits are immediately reflected:
pip install -e .
playwright install chromium
4. Running Tests
Run the test suite locally before creating pull requests:
python -m unittest test_svg2gif.py
CI workflows in .github/workflows/ci.yml will automatically run tests across Python 3.9, 3.10, 3.11, and 3.12 on every push and pull request.
🚀 For Package Publishers & DevOps
1. Automated PyPI Publishing on Push
The repository includes a fully automated release pipeline in .github/workflows/publish.yml.
Whenever you increment the version in pyproject.toml and push to the main branch, the workflow:
- Reads package name and version: Automatically parses the
name(svg2gifpy) andversionfields frompyproject.toml. - Checks PyPI: Checks the official PyPI JSON API to determine if
svg2gifpy==<version>already exists:- If the version already exists: It skips publishing safely (idempotent; no duplicate release errors).
- If the version is new: It executes the release pipeline.
- Runs tests: Runs the complete test suite against the target code.
- Builds distribution: Generates source archive (
.tar.gz) and wheel (.whl) viapython -m build. - Publishes to PyPI: Uploads distributions to PyPI under
svg2gifpy. - Creates GitHub Release: Generates a Git tag (
vX.Y.Z) and GitHub Release with auto-generated release notes and attached distribution artifacts.
2. How to Release a New Version
To release a new version to PyPI:
- Bump the version in
pyproject.toml:[project] name = "svg2gifpy" version = "0.2.0" # <-- Increment version here
- Commit and push to
main:git add pyproject.toml git commit -m "chore: bump version to 0.2.0" git push origin main
- GitHub Actions handles the rest automatically! Monitor progress under the repository's Actions tab.
3. PyPI Authentication Setup
The workflow supports both modern PyPI authentication methods:
Option A: PyPI Trusted Publishing (OIDC) — Recommended
- Go to your PyPI project settings on pypi.org.
- Under Publishing, add a Trusted Publisher:
- Owner:
ishandutta2007 - Repository name:
svg2gif - Workflow name:
publish.yml - Environment name:
pypi
- Owner:
- No secret tokens required!
Option B: PyPI API Token Secret
- Create an API token on pypi.org/manage/account/token/ with upload permissions for
svg2gifpy(or entire account if first upload). - In GitHub, navigate to Settings ➡️ Secrets and variables ➡️ Actions.
- Create a repository secret named
PYPI_API_TOKENand paste your token value (starting withpypi-).
4. Manual Publishing Fallback
If you ever need to publish manually from your local machine:
pip install build twine
python -m build
twine upload dist/*
📄 License
This project is licensed under the MIT License - see the LICENSE file for details.
⭐ Star History
Metadata
Release files for svg2gifpy 0.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 |
|---|---|---|---|---|
| svg2gifpy-0.1.0.tar.gz | 14.1 kB | Without provenance | Details for svg2gifpy-0.1.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| svg2gifpy-0.1.0-py3-none-any.whl | Python 3 | none | any | Details for svg2gifpy-0.1.0-py3-none-any.whl |
Total release size: 25.9 kB
Release files / svg2gifpy-0.1.0.tar.gz
| Download URL | svg2gifpy-0.1.0.tar.gz |
|---|---|
| Size | 14.1 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
99d972adda5d82836c20f188c324380c98b5ead72fc1422f51a83b66dfe9fc24
|
|
BLAKE2b-256 checksum How to use checksums |
cd60e21ee7607eaaac4ac6098e97167c26368d3e303b610bcc09ef509026a630
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Release files / svg2gifpy-0.1.0-py3-none-any.whl
| Download URL | svg2gifpy-0.1.0-py3-none-any.whl |
|---|---|
| Size | 11.8 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
2e9416c0338ef3da8b61cd1469280210b87ba2afae54a90d4a44eff9d3f7bacd
|
|
BLAKE2b-256 checksum How to use checksums |
ab91452fd56e2b65cb00b6a48baf7460acd350e4d1533678aacfbca8d659a3a0
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Security for svg2gifpy 0.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.