When you upload an image to Mastodon, the platform encourages you to add a description, known as alt text, for accessibility. However, the default behavior does not block sending a post if you skip writing that description. This can lead to posts with images that are invisible to users who rely on screen readers or who have images disabled. The lack of a forced prompt means that even well-meaning users may forget to describe their images, reducing the inclusivity of their content. This article explains how to enable a hard reminder on Mastodon that requires you to write alt text before a post is sent.
Key Takeaways: Forcing Alt Text Before Posting on Mastodon
- Preferences > Other > Require media descriptions: Enables a hard check that prevents sending any post with undescibed images.
- Instance admin settings in the Mastodon admin panel: Allows server-wide enforcement of alt text requirements for all users on the instance.
- Third-party clients like Tusky or Fedilab: Offer their own setting to block sending posts without alt text when using those apps.
Why Mastodon Does Not Block Posts Without Alt Text by Default
Mastodon is built on the principle of user autonomy. The platform encourages accessibility but does not impose strict rules on individual users by default. The alt text reminder that appears when you upload an image is advisory, not mandatory. This design choice balances freedom of expression with the goal of promoting accessible content. However, for users who want to guarantee that every image they share includes a description, the default behavior can be frustrating. The feature to enforce alt text exists but must be activated explicitly in your account preferences or, if you are an admin, for your entire instance.
The technical mechanism behind the reminder is a simple flag in the Mastodon source code. When you upload an image, the web interface or client creates an attachment object. That object has a field for a description. If the description field is empty, the post composer shows a visual warning in the form of a red border around the image thumbnail. But the warning does not prevent the post from being sent. The setting to require descriptions changes this behavior by making the composer check the description field before allowing the post to be submitted. If any attachment lacks a description, the send button is disabled and a clear error message appears.
What the Require Media Descriptions Setting Actually Does
When you enable the setting labeled Require media descriptions in your Mastodon preferences, the web interface will block any attempt to post an image without alt text. The same setting applies to the official Mastodon mobile apps for iOS and Android. The check runs at the moment you press the send button. If the composer finds an image with an empty description field, it shows a pop-up message: “One or more of the media attachments you’ve added to this post is missing a description. Please provide a description before sending.” The post will not be sent until every image has a description filled in.
Steps to Enable the Alt Text Reminder in Mastodon
The following steps apply to the Mastodon web interface. The same setting is available in the official mobile apps under the same menu path.
- Open your Mastodon preferences
Click the gear icon in the top-right corner of the Mastodon web interface to open the Preferences menu. On mobile, tap your profile avatar and then tap Preferences. - Navigate to the Other section
In the left sidebar, scroll down and click Other. This section contains miscellaneous settings that affect how the composer behaves. - Enable Require media descriptions
Find the checkbox labeled Require media descriptions. Check the box to turn on the requirement. No save button is needed; the setting takes effect immediately. - Test the setting by composing a new post
Click the compose button to open the post composer. Upload an image and leave the description field blank. Try to send the post. You should see the error message described above, and the post will not be sent. - Add a description to the image
Click on the image thumbnail in the composer. A text field labeled Describe for people with limited vision appears. Type a description of the image content. After filling it in, the send button becomes active again.
Alternative Method: Using Third-Party Apps
If you use a third-party Mastodon client, the setting may be named differently. In Tusky for Android, go to Settings > Posting and enable Require image description. In Fedilab, go to Settings > Composer and toggle Force alt text. These apps implement the same logic: they scan the attachments before sending and block the post if any description is missing.
Common Issues When Enforcing Alt Text on Mastodon
Setting Does Not Block Posts in Some Third-Party Apps
The Require media descriptions setting in Mastodon preferences only applies to the official web interface and official mobile apps. Third-party clients that do not respect the Mastodon API setting will ignore the requirement. If you use an app like Elk, Halcyon, or Pinafore, the setting may not work. To enforce alt text in those apps, check the app’s own settings for a similar option. If the app does not offer one, you cannot force alt text through that client.
Error Message Still Appears When Posting Without Images
Some users report seeing the alt text error even when no images are attached. This happens if you have enabled the setting and then attach a poll or a link card that Mastodon treats as a media attachment. The composer checks all attachment types, including polls. If you see the error on a text-only post, check whether you accidentally added a poll. Remove the poll or add a description to the poll image if one is attached.
Admin-Enforced Alt Text Cannot Be Overridden by Users
If your instance admin has enabled server-wide alt text enforcement, the individual user setting is overridden. You cannot disable the requirement for your own account. In that case, every post with media must include a description. The admin setting is found in the admin panel under Server Settings > Content Retention. The checkbox is labeled Require media descriptions for all users. When enabled, it applies to all accounts on the instance, including new sign-ups.
Mastodon Web Interface vs Third-Party App Alt Text Enforcement
| Item | Mastodon Web Interface | Third-Party Apps (Tusky, Fedilab) |
|---|---|---|
| Setting location | Preferences > Other > Require media descriptions | App-specific settings (Settings > Posting or Settings > Composer) |
| Blocks send without alt text | Yes, when enabled | Yes, when enabled in the app |
| Applies to polls | Yes | Depends on the app |
| Respects admin override | Yes | Only if the app reads the admin setting from the API |
| Works on iOS and Android | Yes (official app) | Only for the specific app |
Enabling alt text enforcement on Mastodon is a straightforward process that improves accessibility for all your followers. The setting is available in your user preferences and takes effect immediately. If you use a third-party client, check its own settings for a similar option. Instance admins can enforce the requirement server-wide through the admin panel. Once enabled, you will never accidentally send an image without a description again.
After turning on the requirement, try composing a post with an image and leaving the description blank to confirm the block works. If you frequently use polls, remember that they are also subject to the check. For the best accessibility experience, also consider adding alt text to GIFs and videos, though Mastodon does not require descriptions for video attachments by default.
One advanced tip: if you use the Mastodon API to post via scripts or automation tools, the Require media descriptions setting does not apply. Those tools bypass the web interface check. To enforce alt text in automated posts, modify your script to check the description field of each attachment before calling the API endpoint to create a status.