Skip to main content

A framework to work with lottie files and telegram animated stickers (tgs)

Project description

Python Lottie

A Python framework to work with Lottie files and Telegram animated stickers.

Quick start

This section describes some common things you might want to do without having to read the whole README


pip install lottie

Converting into images

This package provide the script, it's precise location depends on how you installed python-lottie.

For PNG, GIF, and Webp you have to install cairosvg and pillow.

To render a still image: input_file.json output_file.png --frame 30

To render an animated image (GIF or WebP): input_file.json output_file.webp

A list of supported formats is described in the section "Supported Formats" below.

Turning GIF and such into animations

The lottie format is for vector graphics, this means converting raster images usually doesn't work too well.

That said, python-lottie does support a few different algorithms to import raster images, the process is a bit slow for larger images but use it with caution.

To use the potrace vectorization library, install the extras tagged as "trace".

Once set up, just invoke using the vectorization algorithm input_file.gif output_file.json --bmp-mode trace

For pixel art, you can use the pizel algorithm, which doesn't require potrace input_file.gif output_file.json --bmp-mode pixel

If you are ok with keeping raster images as such, you can use the default mode input_file.gif output_file.json

Converting Telegram animated stickers (tgs)

This format is natively supported by python lottie, but telegram doesn't support all of the features supported by lottie (see the section labeled "Supported After Effects Features" for details).

When converting from tgs, nothing special is needed as it's handled as a lottie animation. AnimatedSticker.tgs output_file.webp

But when converting into animated stickers, you might end up with a file that Telegram doesn't recognize. To help with this, by default will scale the animation to be the right size and framerate. It will also print out any warnings related to unsupported features. Everything else works like any other conversion: input_file.json output_file.tgs

If you want to see the same warnings for an existing tgs file use AnimatedSticker.tgs

Creating animations from scratch

See the examples at and read the available lottie objects at


Here is a list of features of the lottie python framework:

  • Loading compressed TGS and uncompressed lottie JSON
  • Manipulation of lottie objects
  • Simple animation presets (eg: shake, linear bounce)
  • Bezier path animations (eg: follow path, making paths appear and disappear)
  • Wave distortion animation (eg: for flags)
  • Pseudo-3D rotations
  • Animation easing functions
  • Inverse Kinematic solver
  • Pretty printing and comparison of lottie files
  • Rendering text as shapes

Supported Formats

Format Import Import Animated Export Export Animated
lottie ๐Ÿ‘ ๐Ÿ‘ ๐Ÿ‘ ๐Ÿ‘
tgs ๐Ÿ‘ ๐Ÿ‘ ๐Ÿ‘ ๐Ÿ‘
SVG ๐Ÿ‘ ๐Ÿ‘ ๐Ÿ‘ โ›”๏ธ
SVGz ๐Ÿ‘ ๐Ÿ‘ ๐Ÿ‘ โ›”๏ธ
PNG ๐Ÿ‘ ๐Ÿ‘[^frames] ๐Ÿ‘ โ›”๏ธ
Synfig ๐Ÿ‘ ๐Ÿ‘ ๐Ÿ‘ ๐Ÿ‘
WebP ๐Ÿ‘ ๐Ÿ‘ ๐Ÿ‘ ๐Ÿ‘
dotLottie ๐Ÿ‘ ๐Ÿ‘ ๐Ÿ‘ ๐Ÿ‘
PostScript โ›”๏ธ โ›”๏ธ ๐Ÿ‘ โ›”๏ธ
PDF โ›”๏ธ โ›”๏ธ ๐Ÿ‘ โ›”๏ธ
BMP ๐Ÿ‘ ๐Ÿ‘[^frames] โ›”๏ธ โ›”๏ธ
GIF ๐Ÿ‘ ๐Ÿ‘ ๐Ÿ‘ ๐Ÿ‘
TIFF ๐Ÿ‘ ๐Ÿ‘ ๐Ÿ‘ ๐Ÿ‘
MP4 โ›”๏ธ โ›”๏ธ ๐Ÿ‘ ๐Ÿ‘
AVI โ›”๏ธ โ›”๏ธ ๐Ÿ‘ ๐Ÿ‘
WebM โ›”๏ธ โ›”๏ธ ๐Ÿ‘ ๐Ÿ‘
HTML โ›”๏ธ โ›”๏ธ ๐Ÿ‘ ๐Ÿ‘
Blender ๐Ÿ‘[^blend] ๐Ÿ‘[^blend] โ›”๏ธ โ›”๏ธ
Krita ๐Ÿ‘ โ›”๏ธ โ›”๏ธ โ›”๏ธ

[^frames]: Importing multiple images as frames

[^blend]: Conversion available as a Blender addon


python-lottie provides several scripts to convert or manage lottie animations. For full documentation see

The main one is, which can be used to convert between the supported formats.

There is also the script which provides a graphical interface for lottie playback.



The packages for the various applications listed below can be downloaded from here:


There's a Synfig studio plugin to export telegram stickers. To install, just copy (or symlink) ./addons/synfig/pylot-exporter into the synfig plugin directory. You might have to copy ./lib/lottie in there as well.


There are some import/export extensions for inkscape.

Just copy (or symlink) the files under ./addons/inkscape to the inkscape extension directory. On my system that's ~/.config/inkscape/extensions/ but you can double check from Inkscape: Edit > Preferences... > System > User extensions

Note that the extensions require Python 3. If they are run with a python 2 interpreter, they will try to run themselves using python3.

They also need the lottie framework to be in the python path, otherwise you can manually set the path on the import/export dialogues.

See also


There are some export addons for blender.

Copy (or symlink) the files under ./addons/blender to the Blender extension directory.

On my system that's ~/.config/blender/2.80/scripts/addons/ you can check available paths through the Blender Python console:

import addon_utils; print(addon_utils.paths())

You can also install the addon from Blender using the zipfile created by make.


You can install from pypi:

pip install lottie

from git:

pip install git+

for the source directory:

pip install /path/to/the/sources # this is the path where is located


Python 3.

Optional Requirements

In order to provide lean installations, this framework doesn't have dependencies for its core functionality.

To add support for extra formats or advanced functionality, you can install additional packages.

These requirements are declared as extra in the Pypi package, follows a table listing dependencies and features

Packages Extra Feature
pillow images To load image assets
glaxnimate PNG To export PNG
cairosvg PDF To export PNG / PDF / PS
glaxnimate, pillow GIF To export GIF and animated WebP
fonttools text To render text as shapes
grapheme emoji Adding emoji support to text rendering
cairosvg, numpy, Python OpenCV 2 video To export video
glaxnimate trace To convert raster images into vectors
QScintilla GUI Grafical user interface utilities
coverage To show unit test coverage, used optionally by

If intalling from pip, you can install optional requirements like so:

pip install lottie[GIF]

The above example will ensure cairosvg and pillow are installed. For more details see

For convenience, an additional extra requirements is defined, so you can install all dependencies at once:

pip install lottie[all]

If you are using python-lottie from source you can run

pip install -r requirements.txt

Which will install all the requirements (except for pypotrace, as that package has some issues)

Telegram Animated Stickers

I had to reverse engineer the format because Telegram couldn't be bothered providing the specs.

A TGS file is a gzip compressed JSON, the JSON data is described here:

Making your own exporters converters

Lottie format

If you can get the source image into lottie format, that's 90% of the work done.

I've created Python classes based the format schema and after effects documentation, which output the correct json. Eg:

foo = lottie.Animation()
# ...
json.dump(foo.to_dict(), output_file)

I'm also creating a proper documentation for the format, see:

TGS changes

Nothing major, just ensure the root JSON object has tgs: 1


The tgs file is the JSON described above compressed into a gzip, and renamed to .tgs




Copyright 2019 (C) Mattia Basaglia






Here you can download packages for pip, blender, and inkscape before they are released. These packages always have the latest features but they might be unstable.


You can report any issue in the tracker on gitlab:

Supported After Effects Features

Compare with


  • ๐Ÿ‘ Supported
  • โ” Unknown / untested
  • โ›”๏ธ Not supported
  • python-lottie refers to this framework in general
  • Telegram refers to features supported by telegram animated stickers
  • SVG refers to the exported SVG images from this framework, features supported here will also reflect on other formats (such as video, png, and similar)

Telegram doesn't support everything in the Lottie format. lists some things that are unsupported but what is listed there isn't correct.

There are several things marked as unsupported in telegram animated stickers that are actually supported.

Shapes python-lottie Telegram SVG
Shape ๐Ÿ‘ ๐Ÿ‘ ๐Ÿ‘
Ellipse ๐Ÿ‘ ๐Ÿ‘ ๐Ÿ‘
Rectangle ๐Ÿ‘ ๐Ÿ‘ ๐Ÿ‘
Rounded Rectangle ๐Ÿ‘ ๐Ÿ‘ ๐Ÿ‘
Polystar ๐Ÿ‘ ๐Ÿ‘[^unsupported] ๐Ÿ‘
Group ๐Ÿ‘ ๐Ÿ‘ ๐Ÿ‘
Trim Path (individually) ๐Ÿ‘ ๐Ÿ‘ ๐Ÿ‘
Trim Path (simultaneously) ๐Ÿ‘ ๐Ÿ‘ ๐Ÿ‘
Fills python-lottie Telegram SVG
Color ๐Ÿ‘ ๐Ÿ‘ ๐Ÿ‘
Opacity ๐Ÿ‘ ๐Ÿ‘ ๐Ÿ‘
Radial Gradient ๐Ÿ‘ ๐Ÿ‘ ๐Ÿ‘
Linear Gradient ๐Ÿ‘ ๐Ÿ‘ ๐Ÿ‘
Fill Rule ๐Ÿ‘ ๐Ÿ‘ ๐Ÿ‘
Strokes python-lottie Telegram SVG
Color ๐Ÿ‘ ๐Ÿ‘ ๐Ÿ‘
Opacity ๐Ÿ‘ ๐Ÿ‘ ๐Ÿ‘
Width ๐Ÿ‘ ๐Ÿ‘ ๐Ÿ‘
Line Cap ๐Ÿ‘ ๐Ÿ‘ ๐Ÿ‘
Line Join ๐Ÿ‘ ๐Ÿ‘ ๐Ÿ‘
Miter Limit ๐Ÿ‘ ๐Ÿ‘ ๐Ÿ‘
Dashes ๐Ÿ‘ ๐Ÿ‘ ๐Ÿ‘
Gradient ๐Ÿ‘ ๐Ÿ‘[^unsupported] ๐Ÿ‘
Transforms python-lottie Telegram SVG
Position ๐Ÿ‘ ๐Ÿ‘ ๐Ÿ‘
Position (separated X/Y) ๐Ÿ‘ ๐Ÿ‘ ๐Ÿ‘
Scale ๐Ÿ‘ ๐Ÿ‘ ๐Ÿ‘
Rotation ๐Ÿ‘ ๐Ÿ‘ ๐Ÿ‘
Anchor Point ๐Ÿ‘ ๐Ÿ‘ ๐Ÿ‘
Opacity ๐Ÿ‘ ๐Ÿ‘ ๐Ÿ‘
Parenting ๐Ÿ‘ ๐Ÿ‘ ๐Ÿ‘
Skew ๐Ÿ‘ โ›”๏ธ[^bug] ๐Ÿ‘
Auto Orient ๐Ÿ‘ ๐Ÿ‘[^unsupported] ๐Ÿ‘
Interpolation python-lottie Telegram SVG
Linear Interpolation ๐Ÿ‘ ๐Ÿ‘ ๐Ÿ‘
Bezier Interpolation ๐Ÿ‘ ๐Ÿ‘ ๐Ÿ‘
Hold Interpolation ๐Ÿ‘ ๐Ÿ‘ ๐Ÿ‘
Spatial Bezier Interpolation ๐Ÿ‘ ๐Ÿ‘ ๐Ÿ‘
Rove Across Time โ›”๏ธ โ›”๏ธ[^untested] โ›”๏ธ
Masks python-lottie Telegram SVG
Mask Path ๐Ÿ‘ ๐Ÿ‘[^unsupported] ๐Ÿ‘
Mask Opacity ๐Ÿ‘ ๐Ÿ‘[^unsupported] ๐Ÿ‘
Add ๐Ÿ‘ ๐Ÿ‘[^unsupported] โ›”๏ธ
Subtract ๐Ÿ‘ ๐Ÿ‘[^unsupported] โ›”๏ธ
Intersect ๐Ÿ‘ ๐Ÿ‘[^unsupported] ๐Ÿ‘
Lighten ๐Ÿ‘ ๐Ÿ‘[^unsupported] โ›”๏ธ
Darken ๐Ÿ‘ ๐Ÿ‘[^unsupported] โ›”๏ธ
Difference ๐Ÿ‘ ๐Ÿ‘[^unsupported] โ›”๏ธ
Expansion ๐Ÿ‘ ๐Ÿ‘[^unsupported] โ›”๏ธ
Feather ๐Ÿ‘ ๐Ÿ‘[^unsupported] โ›”๏ธ
Mattes python-lottie Telegram SVG
Alpha Matte ๐Ÿ‘ โ›”๏ธ[^dok] ๐Ÿ‘
Alpha Inverted Matte ๐Ÿ‘ โ›”๏ธ[^dok] โ›”๏ธ
Luma Matte ๐Ÿ‘ โ›”๏ธ[^dok] ๐Ÿ‘
Luma Inverted Matte ๐Ÿ‘ โ›”๏ธ[^dok] โ›”๏ธ
Merge Paths python-lottie Telegram SVG
Merge โ›”๏ธ โ›”๏ธ[^untested] โ›”๏ธ
Add โ›”๏ธ โ›”๏ธ[^untested] โ›”๏ธ
Subtract โ›”๏ธ โ›”๏ธ[^untested] โ›”๏ธ
Intersect โ›”๏ธ โ›”๏ธ[^untested] โ›”๏ธ
Exclude Intersection โ›”๏ธ โ›”๏ธ[^untested] โ›”๏ธ
Layer Effects python-lottie Telegram SVG
Fill ๐Ÿ‘ โ›”๏ธ โ›”๏ธ
Stroke ๐Ÿ‘ โ›”๏ธ โ›”๏ธ
Tint ๐Ÿ‘ โ›”๏ธ โ›”๏ธ
Tritone ๐Ÿ‘ โ›”๏ธ โ›”๏ธ
Levels Individual Controls ๐Ÿ‘ โ›”๏ธ โ›”๏ธ
Text [^text] python-lottie Telegram SVG
Glyphs ๐Ÿ‘ โ›”๏ธ โ›”๏ธ
Fonts ๐Ÿ‘ โ›”๏ธ โ›”๏ธ
Transform ๐Ÿ‘ โ›”๏ธ โ›”๏ธ
Fill ๐Ÿ‘ โ›”๏ธ ๐Ÿ‘
Stroke ๐Ÿ‘ โ›”๏ธ โ›”๏ธ
Tracking โ›”๏ธ โ›”๏ธ โ›”๏ธ
Anchor point grouping โ›”๏ธ โ›”๏ธ โ›”๏ธ
Text Path โ›”๏ธ โ›”๏ธ โ›”๏ธ
Per-character 3D โ›”๏ธ โ›”๏ธ โ›”๏ธ
Range selector (Units) โ›”๏ธ โ›”๏ธ โ›”๏ธ
Range selector (Based on) โ›”๏ธ โ›”๏ธ โ›”๏ธ
Range selector (Amount) โ›”๏ธ โ›”๏ธ โ›”๏ธ
Range selector (Shape) โ›”๏ธ โ›”๏ธ โ›”๏ธ
Range selector (Ease High) โ›”๏ธ โ›”๏ธ โ›”๏ธ
Range selector (Ease Low) โ›”๏ธ โ›”๏ธ โ›”๏ธ
Range selector (Randomize order) โ›”๏ธ โ›”๏ธ โ›”๏ธ
expression selector โ›”๏ธ โ›”๏ธ โ›”๏ธ
Other python-lottie Telegram SVG
Expressions โ›”๏ธ โ›”๏ธ[^untested] โ›”๏ธ
Images ๐Ÿ‘ โ›”๏ธ ๐Ÿ‘
Precomps ๐Ÿ‘ ๐Ÿ‘ ๐Ÿ‘
Time Stretch ๐Ÿ‘ โ›”๏ธ โ›”๏ธ
Time remap ๐Ÿ‘ โ›”๏ธ[^dok] ๐Ÿ‘
Markers โ›”๏ธ โ›”๏ธ[^untested] โ›”๏ธ
3D Layers ๐Ÿ‘ โ›”๏ธ[^untested] โ›”๏ธ
Repeaters ๐Ÿ‘ ๐Ÿ‘[^unsupported] ๐Ÿ‘
Solids ๐Ÿ‘ ๐Ÿ‘[^unsupported] ๐Ÿ‘

[^text]: Note that python-lottie offers an alternative to lottie text layers, and can render text as shapes, so that is supported everywhere

[^untested]: Marked as unsupported but I haven't tested it

[^bug]: Not listed as unsupported, maybe a bug?

[^dok]: Works on telegram desktop

[^unsupported]: Marked as unsupported

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

lottie-0.7.0.tar.gz (151.9 kB view hashes)

Uploaded Source

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page