GIFSICLE(1) General Commands Manual GIFSICLE(1)
gifsicle - manipulates GIF images and animations
gifsicle [options, frames, and filenames]...
gifsicle is a powerful command-line program for creating, editing, manipulating, and getting information about GIF images and animations.
Without options, gifsicle acts like a filter: you feed it a GIF on standard input, and it writes that GIF on standard output. That means
these two commands do the same thing:
gifsicle < in.gif > out.gif
gifsicle < in.gif | gifsicle | gifsicle > out.gif
Not too interesting. Most times you'll tell gifsicle to alter its inputs by giving it command line options. The -i option, for example,
tells it to interlace its input files:
gifsicle -i < pic.gif > interlaced-pic.gif
To modify GIF files in place, you should use the --batch option. With --batch, gifsicle will modify the files you specify instead of writ-
ing a new file to the standard output. To interlace all the GIFs in the current directory, you could say:
gifsicle --batch -i *.gif
gifsicle is good at creating and manipulating GIF animations. The simplest way to create an animation is to give more than one input file,
which gifsicle will combine to create a ``flipbook'' animation:
gifsicle pic1.gif pic2.gif pic3.gif > animation.gif
Use options like --delay, --loopcount, and --optimize to tune your animations; see their descriptions for more details.
The bulk of this manual page indexes gifsicle's options and describes them in gory detail. New users may want to skip to the Examples sec-
tion at the end.
This index is meant to help you find options that do what you want. Concepts are on the left, relevant gifsicle options are on the right.
Animations, changing frame selections, frame changes, etc.
portions of frame selections
smaller --optimize, --colors
Bad output --careful
Background color --background
Colors, changing --change-color, --use-colormap, --dither, --transform-colormap
reducing number --colors, --dither
Extensions --extension, --app-extension, --extension-info
File size --optimize, --unoptimize, --colors
cropping --crop, --crop-transparency
resizing --resize, --scale
Positioning frames --position
Screen, logical --logical-screen
Selecting frames frame selections (like '#0')
Web-safe palette --use-colormap
gifsicle's 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.
gifsicle 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.
gifsicle exits with status 0 if there were no errors and status 1 otherwise.
Every option has a long form, `--long-descriptive-name'. You don't need to type the whole long descriptive name, just enough to make it
Some options also have a short form, `-X'. You can combine short options if they don't take arguments: `-IIb' is the same as `-I -I -b'.
But be careful with options that do take arguments: `-cblah' means `-c blah', not `-c -b -l -a -h'.
Many options also have a converse, `--no-option', which turns off the option. You can turn off a short option `-X' by saying `+X' instead.
Mode options tell gifsicle what kind of output to generate. There can be at most one, and it must precede any GIF inputs.
Combine all GIF inputs into one file with multiple frames and write that file to the standard output. This is the default mode.
Modify each GIF input in place by reading and writing to the same filename. (GIFs read from the standard input are written to the
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 `--output') and the numeric extension is the frame number.
Same as --explode, but write any named frames to files `xxx.name' instead of `xxx.frame-number'. Frames are named using the `--name'
General options control the information gifsicle prints and where it writes its output. The info options and --verbose can be turned off
Like --info, but also print information about input files' colormaps. --cinfo is a synonym for --color-info.
Like --info, but also print any unrecognized GIF extensions in a hexdump(1)-like format. --xinfo is a synonym for --extension-info.
Print usage information and exit.
Print a human-readable description of each input GIF to the standard output, or whatever file you specify with -o. This option sup-
presses normal output, and cannot be combined with mode options like --batch. If you give two --info or -I options, however, normal
output is not suppressed; information will be printed on standard error, and you can supply a mode option.
Send output to file. The special filename `-' means the standard output.
Print progress information (files read and written) to standard error.
Suppress all warning messages.
Print the version number and some short non-warranty information and exit.
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.
Like --nextfile, but read 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 gifsicle 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.
#num Select frame num. (The first frame is `#0'. Negative numbers count backwards from the last frame, which is `#-1'.)
#num1-num2 Select frames num1 through num2.
#num1- Select frames num1 through the last frame.
#name 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 out-
put 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
Frame change options insert new frames into an animation or replace or delete frames that already exist. Some things -- for example, chang-
ing one frame in an animation -- are difficult to express with frame selections, but easy with frame changes.
--delete frames [frames...]
Delete frames from the input GIF.
--insert-before frame other-GIFs
Insert other-GIFs before frame in the input GIF.
Append other-GIFs to the input GIF.
--replace frames other-GIFs
Replace frames from the input GIF with other-GIFs.
Complete the current set of frame changes.
The frames arguments are frame selections (see above). These arguments always refer to frames from the original input GIF. So, if `a.gif'
has 3 frames and `b.gif' has one, this command
gifsicle a.gif --delete "#0" --replace "#2" b.gif
will produce an output animation with 2 frames: `a.gif' frame 1, then `b.gif'.
The other-GIFs arguments are any number of GIF input files and frame selections. These images are combined in merge mode and added to the
input GIF. The other-GIFs 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: `--X', `--no-X', and `--same-X'. The `--X' form selects a value for the feature, the `--no-X' form turns off the feature, and the
`--same-X' form means that the feature's value is copied from each input. The default is always `--same-X'. For example, -back-
ground="#0000FF" sets the background color to blue, --no-background turns the background color off (by setting it to 0), and --same-back-
ground 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.
Set the output GIF's background to color. The argument can have the same forms as in the --transparent option below.
Crop the following input frames to a smaller rectangular area. The top-left corner of this rectangle is (x1,y1); you can give either
the lower-right corner, (x2,y2), or the width and height of the rectangle. In the x1,y1+widthxheight form, width and height can be ze-
ro 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, --crop 2,2+-2x-2 will shave 2 pixels off each side of the input image. Crop-
ping 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 --crop 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.
Set the output logical screen to widthxheight. --no-logical-screen sets the output logical screen to the size of the largest output
frame, while --same-logical-screen sets the output logical screen to the largest input logical screen. --screen is a synonym for
Set the following frames' positions to (x,y). --no-position means --position 0,0. Normally, --position x,y places every succeeding
frame exactly at x,y. However, if an entire animation is input, x,y is treated as the position for the animation.
Rotate the following frames by 90, 180, or 270 degrees. --no-rotate turns off any rotation.
Make color transparent in the following frames. Color 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 app-name and with the value extension to the output GIF.
Add a comment, text, to the output GIF. The comment will be placed before the next frame in the stream.
--no-comments and --same-comments affect all the images following, and apply only to input GIF comments, not ones added with --com-
--extension number extension
Add an extension numbered number and with the value extension to the output GIF. Number can be in decimal, octal, hex, or it can be a
single character like `n', whose ASCII value is used.
--no-extensions (or +x) and --same-extensions affect all the images following, and apply only to input GIF extensions.
Set the next frame's name to text. This name is stored as an extension in the output GIF (extension number 0xCE, followed by the
characters of the frame name).
--no-names and --same-names affect all the images following. They apply only to input GIF names, not ones added with --name.
Animation options apply to GIF animations, or to individual frames in GIF animations. As with image options, most animation options have
three forms, `--X', `--no-X', and `--same-X', 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.
Set the delay between frames to time in hundredths of a second.
Set the disposal method for the following frames to method. A frame's disposal method determines how a viewer should remove the frame
when it's time to display the next. Method can be a number between 0 and 7 (although only 0 through 3 are generally meaningful), or
one of these names: none (leave the frame visible for future frames to build upon), asis (same as "none"), background (or bg) (replace
the frame with the background), or previous (replace the frame with the area from the previous displayed frame). --no-disposal means
Set the Netscape loop extension to count. Count is an integer, or forever to loop endlessly. If you supply a --loopcount option with-
out specifying count, Gifsicle will use forever. --no-loopcount (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 --no-loopcount will show ev-
ery frame once; --loopcount=1 will loop once, thus showing every frame twice; and so forth. Note that --loopcount=0 is equivalent to
--loopcount=forever, not --no-loopcount.
Optimize output GIF animations for space. Level determines how much optimization is done; higher levels take longer, but may have
better results. There are currently three levels:
-O1 Stores only the changed portion of each image. This is the default.
-O2 Also uses transparency to shrink the file further.
-O3 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 --same-optimize option.
Unoptimize GIF animations into an easy-to-edit form.
GIF animations are often optimized (see --optimize) to make them smaller and faster to load, which unfortunately makes them difficult
to edit. --unoptimize changes optimized input GIFs into unoptimized GIFs, where each frame is a faithful representation of what a us-
er would see at that point in the animation.
There is no --same-unoptimize option.
Whole-GIF options effect entire GIFs as they are read or written. They can be turned off with `--no-option'.
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 --careful option if you are having problems with a particular image.
--change-color color1 color2
Change color1 to color2 in the following input GIFs. (The color arguments have the same forms as in the -t option.) You can 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. --no-change-color
cancels all color changes.
Reduce the number of distinct colors in each output GIF to num or less. Num must be between 2 and 256. This can be used to shrink
output GIFs or eliminate any local color tables.
Unless you give --use-colormap, an adaptive group of colors is chosen from the existing color table. You can affect this process with
the --color-method option. Gifsicle may need to add an additional color (making num+1 in all) if there is transparency in the image.
Determine how a smaller colormap is chosen. There are three choices: diversity, the default, is xv(1)'s diversity algorithm, which us-
es a strict subset of the existing colors. blend-diversity is a modification of this: some color values are blended from a group of
the existing colors. median-cut is the median cut algorithm described by Heckbert. --method is a synonym for --color-method.
This option only matters if the colormap was changed. With --dither on, Floyd-Steinberg error diffusion is used to approximate any
colors that were removed. This looks better, but makes bigger files and can cause animation artifacts, so it is off by default.
Resize the output GIF to widthxheight. Either width or height may be an underscore `_'. If the argument is widthx_, then the output
GIF is scaled to width pixels wide without changing its aspect ratio. An analogous operation is performed for _xheight. Resizing hap-
pens after all input frames have been combined and before optimization. Gifsicle's resize algorithm is designed for speed, not quali-
ty; for best-looking results you will need to use other tools.
Like --resize widthx_ and --resize _xheight respectively.
Like --resize, but resizes the output GIF to fit within a rectangle with dimensions widthxheight. The GIF's aspect ratio remains un-
changed. No resize is performed if the GIF already fits within the given rectangle. Either width or height may be an underscore `_',
which is treated as infinity.
Like --resize-fit widthx_ and --resize-fit _xheight respectively.
Scale the output GIF's width and height by Xfactor and Yfactor. If Yfactor is not given, it defaults to Xfactor. Scaling happens af-
ter all input frames have been combined and before optimization.
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 --use-colormap below) and piped to the command. The output that command generates (which
should also be in text colormap format) will be used as the colormap instead.
Set the image's colormap to colormap. Colormap can be web for the 216-color ``Web-safe palette''; gray for grayscale; bw 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 --colors=N is also given, an N-sized subset of colormap will be used.
Text colormap files have a very simple 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
Here are a bunch of examples showing how gifsicle is commonly used.
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 --delay option.
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 --loopcount:
gifsicle -d 50 --loop=3 a.gif b.gif c.gif d.gif > anim.gif
(Rather than type --delay again, we used its short form, -d. Many options have short forms; you can see them by running `gifsicle --help'.
We also abbreviated --loopcount to --loop, 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
--unoptimize is used since `anim.gif' was optimized in the last step. Editing individual frames in optimized GIFs is dangerous without
--unoptimize; frames following the changed frame could be corrupted by the change. Of course, this might be what you want.
Note that --unoptimize and --optimize can be on simultaneously. --unoptimize affects input GIF files, while --optimize affects output GIF
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
Giving -I twice forces normal output to occur. With only one -I, 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
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 --careful option.
Please email suggestions, additions, patches and bugs to firstname.lastname@example.org.
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.
The gifsicle home page.
Version 1.67 5 May 2012 GIFSICLE(1)