Mastodon GIF Posting: Supported Sources and Workarounds

You want to post a GIF on Mastodon, but your file keeps getting rejected or plays as a static image. Mastodon supports GIF files, but it converts them to video format MP4 during upload. This conversion process has specific requirements that can cause failures if your source file does not meet them. This article explains which GIF sources work, why some fail, and what to do when a GIF does not upload correctly.

Why Mastodon Converts GIF Files and What It Means for Uploads

Mastodon does not store and serve original GIF files. When you upload a .gif file, the server converts it to an MP4 video file using the H.264 video codec and the AAC audio codec. The server discards any audio track from the source file. This conversion reduces bandwidth usage and improves playback performance across the fediverse.

The conversion process imposes several constraints on the source GIF. The file size limit on most Mastodon instances is 8 MB for the uploaded file. The maximum dimensions for the converted video are 1920 pixels wide and 1080 pixels tall, with a frame rate of 30 frames per second maximum. If your GIF exceeds any of these limits, the server rejects the upload or converts the file to a static image.

The original GIF format supports only 256 colors per frame. Mastodon converts the file to a 24-bit color MP4, which can improve the visual quality of animated content. However, the conversion also changes the file size and dimensions. A large, high-color GIF may end up larger than the original after conversion, causing the upload to fail.

Instance-Specific Upload Limits

Each Mastodon instance administrator can set custom upload limits. The default limit is 8 MB, but some instances raise this to 16 MB or higher. Other instances may lower the limit to 4 MB. Check your instance settings by going to Preferences > Preferences > Appearance and looking for the file size limit displayed near the avatar upload area. If the limit is too low for your GIF, you must compress the file before uploading.

Steps to Post a GIF on Mastodon Successfully

Follow these steps to ensure your GIF uploads correctly and plays as an animation.

1. Check the file size of your GIF
   Right-click the GIF file on your computer and select Properties (Windows) or Get Info (macOS). If the file size exceeds 8 MB, you must compress it. Use an online tool like Ezgif.com or a desktop tool like FFmpeg to reduce the file size. Set the output format to GIF and reduce the frame count or dimensions until the size is under 8 MB.
2. Verify the dimensions of the GIF
   Open the GIF in an image viewer and check the width and height. If the width exceeds 1920 pixels or the height exceeds 1080 pixels, resize the GIF. Use the same online tool or FFmpeg to resize the canvas. For example, with FFmpeg use the command ffmpeg -i input.gif -vf scale=800:-1 output.gif to set the width to 800 pixels while preserving the aspect ratio.
3. Upload the GIF to Mastodon
   Open Mastodon in your web browser or mobile app. Click the attachment icon (paperclip) and select the GIF file. Wait for the upload to complete. The server converts the file to MP4. If the upload finishes without an error, the GIF plays as an animation in your post.
4. Add a content warning or description if needed
   Click the eye icon to mark the media as sensitive if the GIF contains flashing images or adult content. Type a description of the GIF in the text field for accessibility. This step is optional but recommended for compliance with instance rules.
5. Post the message
   Click the Publish button. Your followers see the GIF as an animated MP4 that plays automatically in their timelines.

Using FFmpeg to Convert a Problematic GIF

If your GIF still fails to upload after compression, convert it directly to MP4 using FFmpeg. This bypasses the server-side conversion and gives you control over the output parameters.

1. Install FFmpeg
   Download FFmpeg from ffmpeg.org and install it on your computer. On Windows, add the bin folder to your system PATH. On macOS, use Homebrew with the command brew install ffmpeg.
2. Run the conversion command
   Open a terminal or command prompt. Navigate to the folder containing your GIF. Run this command: ffmpeg -i input.gif -vf scale=800:-1 -r 30 -b:v 1M -c:v libx264 -pix_fmt yuv420p output.mp4. Replace input.gif with your file name and output.mp4 with the desired output name. This command resizes the GIF to 800 pixels wide, sets the frame rate to 30 fps, and encodes the video with H.264 at a bitrate of 1 Mbps.
3. Upload the MP4 file
   Upload the resulting MP4 file to Mastodon. The server accepts MP4 files directly and does not convert them further. Your followers see the animation as a video that plays automatically.

Common Issues When Posting GIFs on Mastodon

GIF Uploads as a Static Image

If your GIF appears as a still image after upload, the conversion process likely failed. The most common cause is a file that exceeds the maximum dimensions or frame rate. Check your GIF dimensions and resize them to under 1920×1080. Reduce the frame rate to 30 fps or lower. If the problem persists, convert the GIF to MP4 using FFmpeg as described above and upload the MP4 file.

Upload Error: File Too Large

Mastodon displays a red error message when the file exceeds the instance limit. Compress the GIF using an online tool or FFmpeg. Reduce the number of frames, lower the color depth, or crop the dimensions. If your instance allows it, ask the administrator to increase the upload limit. Most administrators do not change this setting for security reasons.

GIF Plays Too Fast or Too Slow

The conversion process may alter the playback speed of your GIF. This happens when the original GIF has a non-standard frame delay. To fix this, use FFmpeg to set a specific frame rate. For example, use the -r 15 flag to set the frame rate to 15 fps. Adjust the value until the playback speed matches the original GIF.

Mastodon GIF Posting vs Native MP4 Upload

Item	Uploading a GIF	Uploading an MP4
File format accepted	.gif	.mp4, .webm, .mov
Server-side conversion	Yes, converted to H.264 MP4	No conversion
Color depth	256 colors max in source	24-bit color
File size limit	8 MB default	40 MB default on most instances
Playback behavior	Loops automatically	Loops automatically
Audio support	Discarded	Preserved

Uploading a pre-converted MP4 file avoids the server-side conversion entirely. This gives you more control over the final quality and file size. The MP4 format also supports audio, which GIFs do not. Use this method when your GIF exceeds the conversion limits or when you need to include sound.

You can now post animated content on Mastodon by following the file size and dimension rules. For stubborn GIFs, convert them to MP4 using FFmpeg before uploading. Experiment with different compression settings to balance quality and file size. Always check your instance-specific upload limits in Preferences > Preferences before posting large files.