When you compose a post in Mastodon, you cannot attach more than four images or a single video file in the same post. This limit is enforced by the Mastodon software itself, not by individual server administrators. You might see an error message saying “Too many media attachments” if you try to exceed this rule. This article explains why the limit exists, how to work within it, and what happens when you mix image and video attachments.
Key Takeaways: Mastodon Media Attachment Rules
- Four images maximum per post: You can attach up to four image files in a single post. Any additional image causes an error.
- One video per post only: You cannot attach more than one video file. Attaching a second video replaces the first or triggers a rejection.
- No mixed image and video in one post: If you attach a video, Mastodon ignores any image files you also try to add. The post uses only the video.
Why Mastodon Limits Attachments to Four Images or One Video
Mastodon is a decentralized social network built on the ActivityPub protocol. Each instance stores its own media files. When you attach an image or video to a post, the file is uploaded to your home instance. That instance must then serve the file to all other instances that federate the post. Limiting attachments keeps the storage and bandwidth load manageable for server operators, especially those running small or volunteer-run instances.
The four-image limit is a deliberate design choice. It prevents posts from becoming too large in file size or visual clutter. Mastodon prioritizes text-based conversation over media-heavy posts. The one-video rule exists because video files are significantly larger than images. Allowing multiple videos would quickly consume server disk space and network transfer capacity.
When you try to attach a fifth image, the Mastodon web interface displays an error. The API also rejects the request. This behavior is consistent across all official Mastodon apps and most third-party clients. Server administrators cannot increase or remove the limit through normal settings. The limit is hard-coded in the Mastodon source code.
How to Compose a Post With Attachments Within the Limits
Follow these steps to attach images or a video to your Mastodon post without hitting the limit.
- Open the compose box
Click the compose button in the Mastodon web interface or mobile app. The compose box appears with a text area and media attachment icons. - Click the media attachment icon
The icon looks like a camera or a picture frame. It is usually located below the text area. Clicking it opens your file browser. - Select up to four image files
Hold the Ctrl key on Windows or Command key on Mac to select multiple files. You can choose JPEG, PNG, GIF, or WebP images. Each file must be under the instance file size limit, typically 8 MB or 16 MB. - Or select one video file
If you want to attach a video, select only one video file. Supported formats include MP4, WebM, and MOV. The video must be under the instance video duration limit, usually 40 minutes. - Add alt text to each attachment
Click the edit icon on each attached image or video. In the dialog that opens, type a descriptive alt text. Alt text is required for accessibility. Mastodon will not let you post without alt text on attachments. - Write your post text and publish
Type your message above or below the attachments. Click the publish button. The post appears with the attachments visible to your followers and federated instances.
Common Mistakes and Limitations With Mastodon Attachments
Attaching more than four images
If you try to add a fifth image, the Mastodon interface disables the add button or shows an error. The only workaround is to split the images across multiple posts. You can reply to your first post with the remaining images. This is common for photo threads. Some users create a thread and number each post.
Attaching a video and images together
When you attach a video to a post, any images you also attach are ignored. Mastodon keeps only the video. To include both a video and images, you must post the video in one post and the images in a separate reply. The two posts will appear consecutively on your profile and in follower timelines.
File size or duration exceeds server limits
Each Mastodon instance sets its own maximum file size and video duration. If your file exceeds these limits, the upload fails. Check your instance FAQ or contact your admin for the exact limits. Compress images or shorten videos before uploading to stay within the limits.
Mixed content types in a thread
You can include different attachment types across multiple posts in a thread. For example, post one contains four images. Post two contains a video. Post three contains three images. Each post must individually respect the four-image or one-video rule. The thread as a whole has no combined limit.
Mastodon Attachment Limits vs Other Platforms
| Item | Mastodon | X / Twitter |
|---|---|---|
| Maximum images per post | 4 | 4 |
| Maximum videos per post | 1 | 1 |
| Mixed images and video in one post | Not allowed | Not allowed |
| Maximum file size per image | 8 MB typical, set by instance | 5 MB |
| Maximum video duration | 40 minutes typical, set by instance | 2 minutes 20 seconds |
| Alt text requirement | Required before posting | Optional |
Mastodon and X have the same image and video count limits. The main difference is file size and duration limits. Mastodon gives instances flexibility to set their own limits. X enforces a uniform 5 MB image size and 2 minute 20 second video duration. Mastodon also requires alt text, which X does not enforce.
Now you understand the four-image or one-video rule for Mastodon posts. Use threads to share more than four images or to combine images with a video. Always add alt text to every attachment before publishing. Check your instance media limits in Preferences > Preferences > Appearance or contact your admin for the exact file size and duration values.