You changed your profile picture on your Mastodon home instance, but the old image still shows on other instances. This happens because Mastodon instances cache profile data locally to reduce server load. The cached data does not refresh automatically when you update your avatar. This article explains why the cache blocks the update and shows three reliable methods to force the new picture to appear everywhere.
Key Takeaways: Force a Mastodon Profile Picture Refresh Across Instances
- Ctrl + F5 (Windows) or Cmd + Shift + R (Mac): Performs a hard browser cache refresh to load the new avatar from the server.
- Settings > Appearance > Advanced > Clear cache: Clears the local Mastodon web app cache to force a fresh download of your profile data.
- Third-party server cache flush: Administrators can flush the remote instance cache using the Mastodon API or a manual server command to propagate the update.
Why Mastodon Profile Pictures Get Stuck on Other Instances
Mastodon is a federated network. When you post or update your profile, your home instance sends the new data to remote instances. Those remote instances store a local copy of your profile picture to avoid requesting the image from your home instance every time someone views your profile. This local copy is called a cache.
The cache expiration time depends on the remote instance configuration. Many instances keep cached media for 24 hours or longer. During that window, the remote instance serves the old image to its users. Your home instance shows the new picture immediately because it does not cache its own users data.
Another factor is the browser cache on the viewer side. When a user visits your profile, their browser saves the image URL response. Even if the remote instance updates its cache, the browser may still serve the old file from local storage. This creates a double caching problem that makes the update seem invisible.
Steps to Force a Profile Picture Update Across Instances
Use the methods below in order. Start with the quick browser fix, then clear the Mastodon web app cache, and finally flush the server cache if you have administrative access.
Method 1: Hard Refresh Your Browser Cache
This method forces your browser to ignore its local cache and request the image directly from the server.
- Open your Mastodon profile page
Navigate to your profile URL on any instance where the old picture still appears. - Perform a hard refresh
Press Ctrl + F5 on Windows or Cmd + Shift + R on Mac. The page reloads and the browser requests all resources from the server without using the local cache. - Check the profile picture
If the new image appears, the issue was only the browser cache. If it still shows the old picture, proceed to Method 2.
Method 2: Clear the Mastodon Web App Cache
Mastodon stores some data in the browser using IndexedDB and local storage. Clearing this cache forces the web app to re-fetch your profile data.
- Go to Mastodon settings
Click the gear icon in the right column of the Mastodon web interface to open Settings. - Open Appearance settings
In the left sidebar, click Appearance. - Expand Advanced options
Scroll down and click Show advanced options. - Clear the cache
Click the Clear cache button. A confirmation dialog appears. Click OK. - Reload the page
Press F5 to refresh the page. Your profile picture should now show the updated version.
Method 3: Flush the Server Cache on Your Home Instance
This method requires administrative access to your Mastodon instance. It forces the instance to re-process your profile media and push the update to remote servers.
- Open a terminal or SSH session
Log in to your Mastodon server as a user with sudo privileges. - Run the media cache flush command
Enter the following command:RAILS_ENV=production bin/tootctl media remove --days 0 --include-thumbnails
This removes all cached thumbnails and forces Mastodon to regenerate them on the next request. - Re-upload your profile picture
Go to Preferences > Profile > Avatar and upload the image again. This triggers a new media processing job that creates fresh thumbnails. - Wait for federation
Remote instances may take up to 24 hours to pick up the new image. You can speed this up by asking users on other instances to perform a hard refresh as described in Method 1.
If the Profile Picture Still Does Not Update
Old Image Persists on Specific Third-Party Apps
Third-party Mastodon apps like Tusky, Mammoth, or Ivory often cache profile pictures separately. Close the app completely and reopen it. If the problem continues, clear the app cache through your device settings. On Android, go to Settings > Apps > [App Name] > Storage > Clear cache. On iOS, uninstall and reinstall the app because iOS does not offer a per-app cache clear option.
Image Appears Updated on Some Instances but Not Others
This indicates that some remote instances have a longer cache period than others. There is no way to force a remote instance to flush its cache unless you are the administrator. Wait the standard 24 to 48 hours. If the image still does not update on a specific instance after 48 hours, contact the instance admin and ask them to flush their media cache manually using the tootctl media remove command.
New Image Shows as Broken or Missing
A broken image usually means the file upload failed or the image format is unsupported. Mastodon supports JPEG, PNG, GIF, and WebP. Re-upload the image in one of these formats. If the problem persists, check your instance disk space. A full disk prevents new media from being stored. Ask your admin to run df -h on the server to verify available space.
Mastodon Profile Picture Update Methods: Browser vs App Cache vs Server Flush
| Item | Browser Hard Refresh | Mastodon Web App Cache Clear | Server Media Cache Flush |
|---|---|---|---|
| What it fixes | Viewer browser cache | Mastodon IndexedDB cache | Server-side thumbnails and remote cache |
| Time to apply | 2 seconds | 30 seconds | 5 to 10 minutes |
| Requires admin access | No | No | Yes |
| Effect on remote instances | None | None | Forces re-fetch from your instance |
| Success rate | Low if remote cache is active | Medium | High |
You can now force a profile picture update across Mastodon instances using the browser hard refresh, web app cache clear, or server media flush. Start with the browser method because it takes the least time. If the old picture remains, clear the Mastodon cache in Appearance settings. For persistent issues, ask your instance admin to run the tootctl media remove command. A helpful advanced tip is to set your profile picture to a URL that returns a cache-busting query parameter, such as ?v=2, but Mastodon currently strips query parameters from uploaded media. The most reliable approach is to re-upload the image after clearing the server cache.