You are reading an old version of the documentation (v3.0.0). For the latest version see
Version 3.0.0
Fork me on GitHub

Table Of Contents


class matplotlib.animation.FuncAnimation(fig, func, frames=None, init_func=None, fargs=None, save_count=None, **kwargs)[source]

Bases: matplotlib.animation.TimedAnimation

Makes an animation by repeatedly calling a function func.

fig : matplotlib.figure.Figure

The figure object that is used to get draw, resize, and any other needed events.

func : callable

The function to call at each frame. The first argument will be the next value in frames. Any additional positional arguments can be supplied via the fargs parameter.

The required signature is:

def func(frame, *fargs) -> iterable_of_artists:
frames : iterable, int, generator function, or None, optional

Source of data to pass func and each frame of the animation

If an iterable, then simply use the values provided. If the iterable has a length, it will override the save_count kwarg.

If an integer, then equivalent to passing range(frames)

If a generator function, then must have the signature:

def gen_function() -> obj:

If None, then equivalent to passing itertools.count.

In all of these cases, the values in frames is simply passed through to the user-supplied func and thus can be of any type.

init_func : callable, optional

A function used to draw a clear frame. If not given, the results of drawing from the first item in the frames sequence will be used. This function will be called once before the first frame.

If blit == True, init_func must return an iterable of artists to be re-drawn.

The required signature is:

def init_func() -> iterable_of_artists:
fargs : tuple or None, optional

Additional arguments to pass to each call to func.

save_count : int, optional

The number of values from frames to cache.

interval : number, optional

Delay between frames in milliseconds. Defaults to 200.

repeat_delay : number, optional

If the animation in repeated, adds a delay in milliseconds before repeating the animation. Defaults to None.

repeat : bool, optional

Controls whether the animation should repeat when the sequence of frames is completed. Defaults to True.

blit : bool, optional

Controls whether blitting is used to optimize drawing. Note: when using blitting any animated artists will be drawn according to their zorder. However, they will be drawn on top of any previous artists, regardless of their zorder. Defaults to False.


Creates a new sequence of frame information.


Creates a new sequence of saved/cached frame information.

save(filename, writer=None, fps=None, dpi=None, codec=None, bitrate=None, extra_args=None, metadata=None, extra_anim=None, savefig_kwargs=None)

Saves a movie file by drawing every frame.

filename : str

The output filename, e.g., mymovie.mp4.

writer : MovieWriter or str, optional

A MovieWriter instance to use or a key that identifies a class to use, such as 'ffmpeg'. If None, defaults to rcParams["animation.writer"].

fps : number, optional

Frames per second in the movie. Defaults to None, which will use the animation's specified interval to set the frames per second.

dpi : number, optional

Controls the dots per inch for the movie frames. This combined with the figure's size in inches controls the size of the movie. If None, defaults to rcParams["savefig.dpi"].

codec : str, optional

The video codec to be used. Not all codecs are supported by a given MovieWriter. If None, default to rcParams["animation.codec"].

bitrate : number, optional

Specifies the number of bits used per second in the compressed movie, in kilobits per second. A higher number means a higher quality movie, but at the cost of increased file size. If None, defaults to rcParams["animation.bitrate"].

extra_args : list, optional

List of extra string arguments to be passed to the underlying movie utility. If None, defaults to rcParams["animation.extra_args"].

metadata : Dict[str, str], optional

Dictionary of keys and values for metadata to include in the output file. Some keys that may be of use include: title, artist, genre, subject, copyright, srcform, comment.

extra_anim : list, optional

Additional Animation objects that should be included in the saved movie file. These need to be from the same matplotlib.figure.Figure instance. Also, animation frames will just be simply combined, so there should be a 1:1 correspondence between the frames from the different animations.

savefig_kwargs : dict, optional

Is a dictionary containing keyword arguments to be passed on to the savefig command which is called repeatedly to save the individual frames.


fps, codec, bitrate, extra_args, metadata are used to construct a MovieWriter instance and can only be passed if writer is a string. If they are passed as non-None and writer is a MovieWriter, a RuntimeError will be raised.


Returns animation as an HTML5 video tag.

This saves the animation as an h264 video, encoded in base64 directly into the HTML5 video tag. This respects the rc parameters for the writer as well as the bitrate. This also makes use of the interval to control the speed, and uses the repeat parameter to decide whether to loop.

to_jshtml(fps=None, embed_frames=True, default_mode=None)

Generate HTML representation of the animation