manipulates GIF images and animations
[options, frames, and filenames]...
is a powerful command-line program for creating, editing, manipulating, and
getting information about GIF images and animations.
normally processes input GIF files according to its command line
options and writes the result to the standard output. The
option, for example, tells
to interlace its inputs:
gifsicle -i < pic.gif > interlaced-pic.gif
is good at creating and manipulating GIF animations. By default, it
combines two or more input files into a “flipbook” animation:
gifsicle pic1.gif pic2.gif pic3.gif > animation.gif
Use options like
--delay, --loopcount, and --optimize
to tune your animations.
To modify GIF files in place, use the
will modify the files you specify instead of writing a new file to the
standard output. To interlace all the GIFs in the current directory, you
gifsicle --batch -i *.gif
New users may want to skip to
the Examples section at the end.
Concepts are on the left, relevant
options are on the right.
- Image transformations
command line consists of GIF input files and options. Most options start
with a dash (-) or plus (+); frame selections, a kind of option, start
with a number sign (#). Anything else is a GIF input file.
reads and processes GIF input files in order. If no GIF input file is
given, or you give the special filename ‘-’,
it reads from the standard input.
exits with status 0 if there were no errors and status 1 otherwise.
Every option has a long form,
You don’t need to type the whole long descriptive name, just enough to
make it unambiguous.
Some options also have a short form,
You can combine short options if they don’t take arguments:
is the same as
‘-I -I -b’.
But be careful with options that do take arguments:
‘-c -b -l -a -h’.
Many options also have a converse,
which turns off the option. You can turn off a short option
Mode options tell
what kind of output to generate. There can be at most one, and it must
precede any GIF inputs.
- --merge, -m
- Combine all GIF inputs into one file with multiple frames and write that
file to the standard output. This is the default mode.
- --batch, -b
- Modify each GIF input in place by reading and writing to the same filename.
(GIFs read from the standard input are written to the standard output.)
- --explode, -e
- Create an output GIF for each frame of each input file. The output GIFs are
named ‘xxx.000’, ‘xxx.001’, and so on, where ‘xxx’ is the name of the input
file (or whatever you specified with
and the numeric extension is the frame number.
- --explode-by-name, -E
- Same as
but write any named frames to files ‘xxx.name’ instead of
‘xxx.frame-number’. Frames are named using the
General options control the information
prints and where it writes its output. The info options and
can be turned off with
- --info, -I
- Print a human-readable description of each input GIF to the standard
output, or whatever file you specify with
This option suppresses normal output, and cannot be combined with mode
If you give two
options, however, information is printed to standard error, and normal
output takes place as usual.
- --color-info, --cinfo
but also print information about input files’ colormaps.
- --extension-info, --xinfo
but also print any unrecognized GIF extensions in a
- --size-info, --sinfo
but also print information about compressed image sizes.
- --help, -h
- Print usage information and exit.
- -o file
- --output file
- Send output to
The special filename ‘-’ means the standard output.
- --verbose, -V
- Print progress information (files read and written) to standard
- --no-warnings, -w
- Suppress all warning messages.
- Print the version number and some short non-warranty information and exit.
- Write slightly larger GIFs that avoid bugs in some other GIF
implementations. Some Java and Internet Explorer versions cannot display
the correct, minimal GIFs that Gifsicle produces. Use the
option if you are having problems with a particular image.
- Conserve memory usage at the expense of processing time. This may be useful
if you are processing large GIFs on a computer without very much memory.
- Allow input files to contain multiple concatenated GIF images. If a
filename appears multiple times on the command line, gifsicle will
read a new image from the file each time. This option can help scripts
avoid the need for temporary files. For example, to create an animated GIF
with three frames with different delays, you might run "gifsicle
--nextfile -d10 - -d20 - -d30 - > out.gif" and write the three
GIF images, in sequence, to gifsicle’s standard input.
as many GIF images as possible
from each file. This option is intended for scripts. For example, to merge
an unknown number of GIF images into a single animation, run "gifsicle
--multifile - > out.gif" and write the GIF images, in sequence, to
gifsicle’s standard input. Any frame selections apply only to the
last file in the concatenation.
A frame selection tells
which frames to use from the current input file. They are useful only for
animations, as non-animated GIFs only have one frame. Here are the
acceptable forms for frame specifications.
- Select frame num. (The first frame is
Negative numbers count backwards from the last frame, which is
- Select frames num1 through num2.
- Select frames num1 through the last frame.
- Select the frame named name.
The ‘#’ character has special meaning for many shells, so you generally
need to quote it.
gifsicle happy.gif "#0"
uses the first frame from happy.gif;
gifsicle happy.gif "#0-2"
uses its first three frames; and
gifsicle happy.gif "#-1-0"
uses ‘happy.gif’s frames in reverse order (starting from frame #-1—the
last frame—and ending at frame #0—the first).
The action performed with the selected frames depends on the current
mode. In merge mode, only the selected frames are merged into the output
GIF. In batch mode, only the selected frames are modified; other frames
remain unchanged. In explode mode, only the selected frames are exploded
into output GIFs.
Frame change options insert new frames into an animation or replace or
delete frames that already exist. Some things—for example, changing one
frame in an animation—are difficult to express with frame selections, but
easy with frame changes.
- --delete frames [frames...]
from the input GIF.
- --insert-before frame other-GIFs
in the input GIF.
- --append other-GIFs
to the input GIF.
- --replace frames other-GIFs
from the input GIF with
- Complete the current set of frame changes.
arguments are frame selections (see above). These arguments always refer to
frames from the
input GIF. So, if ‘a.gif’ has 3 frames and ‘b.gif’ has one, this
gifsicle a.gif --delete "#0" --replace "#2" b.gif
will produce an output animation with 2 frames: ‘a.gif’ frame 1, then
arguments are any number of GIF input files and frame selections.
These images are combined in merge mode and added to the input GIF.
last until the next frame change option, so this command replaces the
first frame of ‘in.gif’ with the merge of ‘a.gif’ and ‘b.gif’:
gifsicle -b in.gif --replace "#0" a.gif b.gif
This command, however, replaces the first frame of ‘in.gif’ with
‘a.gif’ and then processes ‘b.gif’ separately:
gifsicle -b in.gif --replace "#0" a.gif --done b.gif
Warning: You shouldn’t use both frame selections and frame changes on
the same input GIF.
Image options modify input images—by changing their interlacing,
transparency, and cropping, for example. Image options have three forms:
form selects a value for the feature, the
form turns off the feature, and the
form means that the feature’s value is copied from each input. The default
sets the background color to blue,
turns the background color off (by setting it to 0), and
uses input images’ existing background colors. You can give each option
multiple times; for example,
gifsicle -b -O2 -i a.gif --same-interlace b.gif c.gif
will make ‘a.gif’ interlaced, but leave ‘b.gif’ and ‘c.gif’ interlaced only
if they were already.
- -B color
- --background color
- Set the output GIF’s background to
The argument can have the same forms as in the
- --crop x1,y1-x2,y2
- --crop x1,y1+widthxheight
- Crop the following input frames to a smaller rectangular area. The top-left
corner of this rectangle is
you can give either the lower-right corner,
or the width and height of the rectangle. In the
can be zero or negative. A zero dimension means the cropping area goes to
the edge of the image; a negative dimension brings the cropping area that
many pixels back from the image edge. For example,
will shave 2 pixels off each side of the input image. Cropping takes place
before any rotation, flipping, resizing, or positioning.
- Crop any transparent borders off the following input frames. This happens
after any cropping due to the
option. It works on the raw input images; for example, any transparency
options have not yet been applied.
- Flip the following frames horizontally or vertically.
- Turn interlacing on.
- -S widthxheight
- --logical-screen widthxheight
- Set the output logical screen to
sets the output logical screen to the size of the largest output
sets the output logical screen to the largest input logical screen.
is a synonym for
- -p x,y
- --position x,y
- Set the following frames’ positions to
places every succeeding frame exactly at x,y. However, if an
entire animation is input, x,y is treated as the position for
- Rotate the following frames by 90, 180, or 270 degrees.
turns off any rotation.
- -t color
- --transparent color
transparent in the following frames.
can be a colormap index (0-255), a hexadecimal color specification
(like "#FF00FF" for magenta), or slash- or comma-separated red, green
and blue values (each between 0 and 255).
Extension options add non-visual information to the output GIF. This
includes names, comments, and generic extensions.
- -x app-name extension
- --app-extension app-name extension
- Add an application extension named
and with the value
to the output GIF.
- -c text
- --comment text
- Add a comment,
to the output GIF. The comment will be placed before the next frame in
affect all the images following, and apply only to input GIF comments,
not ones added with
- --extension number extension
- Add an extension numbered
and with the value
to the output GIF.
can be in decimal, octal, hex, or it can be a single character like ‘n’,
whose ASCII value is used.
affect all the images following, and apply only to input GIF extensions.
- -n text
- --name text
- Set the next frame’s name to
This name is stored as an extension in the output GIF (extension number
0xCE, followed by the characters of the frame name).
affect all the images following. They apply only to input GIF names,
not ones added with
Animation options apply to GIF animations, or to individual frames in GIF
animations. As with image options, most animation options have three forms,
and you can give animation options multiple times; for example,
gifsicle -b a.gif -d50 "#0" "#1" -d100 "#2" "#3"
sets the delays of frames 0 and 1 to 50, and frames 2 and 3 to 100.
- -d time
- --delay time
- Set the delay between frames to
in hundredths of a second.
- -D method
- --disposal method
- Set the disposal method for the following frames to
A frame’s disposal method determines how a viewer should remove the frame
when it’s time to display the next.
can be a number between 0 and 7 (although only 0 through 3 are
generally meaningful), or one of these names:
(leave the frame visible for future frames to build upon),
(same as "none"),
background (or bg)
(replace the frame with the background), or
(replace the frame with the area from the previous displayed frame).
- Set the Netscape loop extension to
is an integer, or
to loop endlessly. If you supply a
option without specifying
Gifsicle will use
(the default) turns off looping.
Set the loop count to one less than the number of times you want the
animation to run. An animation with
will show every frame once;
will loop once, thus showing every frame twice; and so forth.
is equivalent to
- Optimize output GIF animations for space.
determines how much optimization is done; higher levels take longer, but
may have better results. There are currently three levels:
- Stores only the changed portion of each image. This is the default.
- Also uses transparency to shrink the file further.
- Try several optimization methods (usually slower, sometimes better results).
Other optimization flags provide finer-grained control.
- Preserve empty transparent frames (they are dropped by default).
There is no
- Unoptimize GIF animations into an easy-to-edit form.
GIF animations are often optimized (see
to make them smaller and faster to load, which unfortunately makes them
difficult to edit.
changes optimized input GIFs into unoptimized GIFs, where each frame is a
faithful representation of what a user would see at that point in the
There is no
Image transformation options apply to entire GIFs as they are read or
written. They can be turned off with
- --resize widthxheight
- Resize the output GIF to
may be an underscore ‘_’. If the argument is
then the output GIF is scaled to
pixels wide without changing its aspect ratio. An analogous operation is
Resizing happens after all input frames have been combined and before
optimization. Resizing uses logical screen dimensions; if
the input stream has an unusual logical screen (many GIF displayers ignore
logical screens), you may want to provide
to reset it so
uses image dimensions instead. See also
- --resize-width width
- --resize-height height
- --resize-fit widthxheight
but resizes the output GIF to fit
a rectangle with dimensions
The GIF’s aspect ratio remains unchanged. No resize is performed if the GIF already
fits within the given rectangle. Either
may be an underscore ‘_’, which is treated as infinity.
- --resize-fit-width width
- --resize-fit-height height
- --scale Xfactor[xYfactor]
- Scale the output GIF’s width and height by
Xfactor and Yfactor.
is not given, it defaults to
Scaling happens after all input frames have been combined and before
- --resize-method method
- Set the method used to resize images. The ‘sample’ method runs
very quickly, but when shrinking images, it produces noisy results.
The ‘mix’ method is somewhat slower, but produces better-looking
results. The default method is
Details: The resize methods differ most when shrinking images. The
‘sample’ method is a point sampler. Each pixel position in the
output image maps to exactly one pixel position in the input, so when
shrinking, full rows and columns from the input are dropped. The other
methods use all input pixels, which generally produces better-looking
images. The ‘box’ method, a box sampler, is faster than the more
complex filters and produces somewhat sharper results, but there will
be anomalies when shrinking images by a small amount in one dimension.
(Some output pixels will correspond to exactly 1 input row or column,
while others will correspond to exactly 2 input rows or columns.) The
‘mix’ method is a full bilinear interpolator. This is slower and
produces somewhat blurrier results, but avoids such anomalies.
Gifsicle also supports several complex resamplers, including
Catmull-Rom cubic resampling (‘catrom’), the Mitchell-Netravali
filter (‘mitchell’), a 2-lobed Lanczos filter
(‘lanczos2’), and a 3-lobed Lanczos filter (‘lanczos3’).
These filters are slower still, but can give sharper, better results.
- --resize-colors n
- Allow Gifsicle to add intermediate colors when resizing images.
Normally, Gifsicle’s resize algorithms use input images’ color
palettes without changes. When shrinking images with very few colors
(e.g., pure black-and-white images), adding intermediate colors can
improve the results. Example:
allows Gifsicle to add intermediate colors for images that have fewer
than 64 input colors.
Color options apply to entire GIFs as they are read or
written. They can be turned off with
- -k num
- --colors num
- Reduce the number of distinct colors in each output GIF to
must be between 2 and 256. This can be used to shrink output GIFs or
eliminate any local color tables.
Normally, an adaptive group of colors is chosen from the existing
color table. You can affect this process with the
option or by giving your own colormap with
Gifsicle may need to add an additional color (making
in all) if there is transparency in the image.
- --color-method method
- Determine how a smaller colormap is chosen.
the default, is
diversity algorithm, which uses a strict subset of the existing colors
and generally produces good results.
is a modification of this: some color values are blended from groups of
is the median cut algorithm described by Heckbert.
is a synonym for
is on and the colormap is changed, combinations of colors are used to
approximate missing colors. This looks better, but makes bigger files
and can cause animation artifacts, so it is off by default.
Specify a dithering algorithm with the optional method argument.
uses Floyd-Steinberg error
diffusion. This usually looks best, but can cause animation artifacts,
because dithering choices will vary from frame to frame. Gifsicle also
supports ordered dithering algorithms that avoid animation artifacts.
mode uses a
large, random-looking pattern and generally produces good results. The
modes use smaller, more
regular patterns. The
mode chooses a good ordered
dithering algorithm. For special effects, try the halftone modes
Some modes take optional parameters using commas. The halftone modes
take a cell size and a color limit:
creates 10-pixel wide halftone cells where each cell uses up to 3
- --gamma gamma
- Set the gamma correction to
which can be a real number or
Roughly speaking, higher
numbers exaggerate shadows and lower numbers exaggerate highlights.
The default is the function defined by the standard sRGB color space,
which usually works well. (Its effects are similar to
--gamma=2.2.) Gifsicle uses gamma correction when choosing a
color palette (--colors) and when dithering
- --change-color color1 color2
in the following input GIFs. (The
arguments have the same forms as in the
option.) Change multiple colors by giving the option multiple
times. Color changes don’t interfere with one another, so you can safely
swap two colors with
‘--change-color color1 color2 --change-color color2 color1’.
They all take effect as an input GIF is read.
cancels all color changes.
- --transform-colormap command
should be a shell command that reads from standard input and writes to
standard output. Each colormap in the output GIF is translated into text
colormap format (see
below) and piped to the command. The output that command generates
(which should also be in text colormap format) will replace the input
colormap. The replacement doesn’t consider color matching, so pixels
that used color slot
in the input will still use color slot
in the output.
- --use-colormap colormap
- Change the image to use
Each pixel in the image is changed to the closest match in
is on, to a dithered combination of colors in
for the 216-color “Web-safe palette”;
for black-and-white; or the name of a file. That file should either be a
text file (the format is described below) or a GIF file, whose global
colormap will be used. If
is also given, an
will be used.
Text colormap files use this format:
; each non-comment line represents one color, "red green blue"
; each component should be between 0 and 255
0 0 0 ; like this
255 255 255
; or use web hex notation
#ffffff ; like this
First, let’s create an animation, ‘anim.gif’:
gifsicle a.gif b.gif c.gif d.gif > anim.gif
This animation will move very quickly: since we didn’t specify a delay, a
browser will cycle through the frames as fast as it can. Let’s slow it down
and pause .5 seconds between frames, using the
gifsicle --delay 50 a.gif b.gif c.gif d.gif > anim.gif
If we also want the GIF to loop three times, we can use
gifsicle -d 50 --loop=3 a.gif b.gif c.gif d.gif > anim.gif
(Rather than type
again, we used its short form,
Many options have short forms; you can see them by running
We also abbreviated
which is OK since no other option starts with ‘loop’.)
To explode ‘anim.gif’ into its component frames:
gifsicle --explode anim.gif
anim.gif anim.gif.000 anim.gif.001 anim.gif.002 anim.gif.003
To optimize ‘anim.gif’:
gifsicle -b -O2 anim.gif
To change the second frame of ‘anim.gif’ to ‘x.gif’:
gifsicle -b --unoptimize -O2 anim.gif --replace "#1" x.gif
is used since ‘anim.gif’ was optimized in the last step. Editing
individual frames in optimized GIFs is dangerous without
frames following the changed frame could be corrupted by the change.
Of course, this might be what you want.
can be on simultaneously.
GIF files, while
To print information about the first and fourth frames of ‘anim.gif’:
gifsicle -I "#0" "#3" < anim.gif
To make black the transparent color in all the GIFs in the current
directory, and also print information about each:
gifsicle -bII --trans "#000000" *.gif
twice forces normal output to occur. With only one
the GIFs would not be modified.
To change ‘anim.gif’ to use a 64-color subset of the Web-safe palette:
gifsicle -b --colors=64 --use-col=web anim.gif
To make a dithered black-and-white version of ‘anim.gif’:
gifsicle --dither --use-col=bw anim.gif > anim-bw.gif
To overlay one GIF atop another—producing a one-frame output GIF that
looks like the superposition of the two inputs—use
gifsicle bottom.gif top.gif | gifsicle -U "#1" > result.gif
Some optimized output GIFs may appear incorrectly on some GIF
implementations (for example, Java’s); see the
Please email suggestions, additions, patches and bugs to
For a tutorial on GIF images and animations, you might try some of the
resources listed on-line at webreference.com:
Eddie Kohler <email@example.com>
He wrote it.
Anne Dudfield <firstname.lastname@example.org>
She named it.
Hans Dinsen-Hansen <email@example.com>
Adaptive tree method for GIF writing.