Mastodon profiles display a square avatar image by default. Some instances and client apps offer the ability to overlay a decorative frame around that avatar, similar to profile picture frames on other social networks. A custom avatar frame can help your profile stand out or show support for a cause. This article explains how to set a custom avatar frame on your Mastodon profile using the web interface and supported third-party tools.
Key Takeaways: Setting a Custom Avatar Frame on Mastodon
- Profile > Edit profile > Avatar frame: Upload a PNG frame image with a transparent center to overlay on your avatar.
- Image requirements: The frame must be 400×400 pixels, PNG format, with the center area transparent.
- Third-party tools (e.g., Mastodon Profile Frame Generator): Use external websites to create a frame image if your instance does not support direct upload.
Understanding Avatar Frames on Mastodon
An avatar frame is a PNG image overlay that sits on top of your profile picture. The frame has a transparent cutout in the center so your avatar shows through. Mastodon does not have a native feature to apply frames server-side. Instead, the frame is part of the avatar image itself, composited locally by the user or by a client app.
How Frames Work
When you upload a frame through a supported Mastodon client or third-party tool, the tool merges your avatar with the frame image into a single PNG. The resulting file is then uploaded as your regular avatar. The frame is not a separate layer stored on the server. It becomes part of the avatar permanently unless you replace it.
Supported Clients
Most Mastodon instances do not have a dedicated frame upload field in the web interface. The feature is more common in third-party clients such as Tusky (Android) and Mastonews (iOS). Some custom instances, especially those run by communities or brands, may add a frame option using a custom theme or extension.
Steps to Set a Custom Avatar Frame Using the Web Interface
If your Mastodon instance supports avatar frames directly, follow these steps:
- Prepare the frame image
Create or download a PNG image that is 400×400 pixels. The center area must be transparent so your avatar shows through. Use an image editor like GIMP or Photoshop to add transparency. Save the file as frame.png. - Open your profile settings
Click the gear icon in the top-right corner of the Mastodon web interface and choose Preferences. Then select Profile from the left navigation menu. - Upload the avatar frame
Scroll to the Avatar frame section. Click Browse or Choose file and select your frame.png file. Click Save changes at the bottom of the page. - Verify the result
Navigate to your profile page. The frame should appear around your avatar. If the center is not transparent, your avatar will be partially hidden. Re-edit the frame image to ensure the center is fully transparent.
Steps to Set a Custom Avatar Frame Using a Third-Party Tool
If your instance does not have a frame upload option, use a third-party frame generator to composite the frame onto your avatar.
- Choose a frame generator
Open a website like the Mastodon Profile Frame Generator (mastodon-frame-generator.glitch.me) or a similar tool. These sites let you upload your avatar and select a frame design. - Upload your avatar and frame
Click the upload button for your avatar image. Then select a preset frame or upload your own frame PNG. The tool will show a preview of the combined image. - Download the composited image
Once the preview looks correct, click the download button. The tool will save a single PNG file that contains your avatar with the frame overlaid. - Upload the composited image as your avatar
Go to Preferences > Profile in Mastodon. Under Avatar, click Browse and select the downloaded composite PNG. Click Save changes.
Common Mistakes and Limitations
Frame Not Appearing After Upload
If the frame does not show, the most likely cause is that your instance does not support the frame feature. Check with your instance admin or look for a frame field in your profile settings. If the field is missing, you must use the third-party compositing method.
Avatar Cropped Incorrectly
Mastodon crops avatars to a square. If your frame is not square, parts will be cut off. Always use a 400×400 pixel square frame image. The transparent center should be large enough to show your full avatar face.
Frame Looks Pixelated
Low-resolution frame images will appear blurry when scaled. Use a frame image that is at least 400×400 pixels. If the frame has text or fine details, start with a 600×600 pixel image and scale down before uploading.
Frame Overlaps Avatar Badly
If the frame covers too much of your avatar, the transparent area is too small. Edit the frame image to enlarge the transparent center. Test with a temporary avatar to adjust the cutout size.
| Item | Direct Frame Upload | Third-Party Compositing |
|---|---|---|
| Description | Upload a separate frame image in profile settings | Merge frame and avatar into one image using an external tool |
| Instance support required | Yes — instance must have the feature enabled | No — works on any instance |
| Frame is editable later | Yes — you can replace the frame without changing your avatar | No — frame is baked into the avatar; replace entire avatar to change frame |
| Ease of use | Simple — one upload | Requires external tool and two uploads |
The direct upload method is cleaner because the frame stays separate from the avatar. However, few instances support it. The compositing method works everywhere but makes future frame changes more work.
To remove a frame made with compositing, upload a fresh copy of your original avatar without the frame overlay. For direct frame uploads, go to Preferences > Profile > Avatar frame and click Remove or upload a transparent placeholder frame.
If you want to create your own frame design, use an image editor with layer support. Place your frame design on the top layer and make the center area transparent. Export as PNG with transparency enabled. Test the frame on a test account before applying it to your main profile.