Mastodon 5.0 Beta: Self-Hosted Upgrade Guide — What's New, What Breaks, How to Fix It

On October 20, 2026, the Mastodon team shipped the first 5.0 beta so server administrators can test the biggest redesign in the project's history before the stable release lands in a few weeks (Mastodon blog). If you self-host, this version bump matters more than most: the entire web interface has been rebuilt from the ground up.

This is the no-fluff admin guide: what's new in 5.0, what can break, and the documented upgrade path for source and Docker installs. Every fact is verified against the 5.0 announcement, the August foundation post, the public roadmap, and the official upgrade docs. Anything unconfirmed is labeled as such — not guessed.

⚠️ Beta means beta. Beta means testing, not production. Clone your instance to staging, upgrade there, and report issues on the official Discourse forum. Don't touch production until stable 5.0 ships.

What's New in Mastodon 5.0 (Verified)

A brand-new composer

The sidebar-embedded composer is gone: 5.0 uses a pop-out overlay docked at the bottom centre, minimisable without losing a draft. A prominent "New post" button sits lower in the navigation, and on mobile the floating button launches the composer immediately.

Visibility controls are rebuilt for clarity. "Quiet public" becomes an accurate sub-setting — "Discoverable in public feeds & search results" — and sensitive media and content warnings are now separate options in the gear menu. Quote settings start with an "Allow others to quote" toggle (everyone or followers only); followers-only posts can only be quoted by you. Visibility still can't change after publishing; quote settings can.

Rebuilt navigation, feeds, and themes

Navigation is now a single column, with your server's name and icon top-left under a small "Powered by Mastodon" indicator — set these under Preferences → Administration → Server Settings → Branding. Posts were rebuilt from the ground up, five new colour themes ship, and two new Advanced Settings toggles control whether your own posts and boosts appear in your home feed. Lists are renamed "Custom feeds" with a permanent nav spot. The advanced multi-column UI is not gone, and local/federated feeds stay (if enabled).

"Messages" replace private mentions

"Private mention(s)" — a term users consistently misunderstood — is now "message(s)" with a chat-bubble icon. DMs get a dedicated composer ("New message" header, "Send" instead of "Publish") and no longer appear in timelines or profile pages — Messages page only. Expect "where did my DMs go?" tickets after the upgrade; now you know the answer.

Shared blocklists for admins

Per the public roadmap, 5.0 lets admins subscribe to external blocklists — as suggestions or auto-applied. For single-admin instances, this is the most useful 5.0 feature: moderation leverage without a team.

What Can Break: The Admin Checklist

• Custom CSS will likely need rework. Posts, navigation, and the composer were rebuilt on a newly tokenised design system — custom styles for the old markup are suspect until re-verified on staging.
• User confusion is a support load, not a bug. The composer moved, DMs left the timeline, lists became "custom feeds," the "quiet public" label vanished. Share the official blog posts with your users and pre-empt the tickets.
• System requirements may change. The 5.0 beta release notes are where the team publishes requirement bumps — unconfirmed at writing time, and past majors have raised minimum Ruby/Node versions. Read the 5.0 beta notes before upgrading; don't assume 4.7's requirements carry over.
• Don't skip asset precompilation. The team shipped a custom Rails/Vite integration (August engineering update), and the frontend is entirely rebuilt — precompile assets as part of every upgrade, per the docs.

✅ The pattern holds. Read the release notes first, back up second, upgrade third — the same discipline as our Pi-hole v6.5 safe-update guide and Immich V2 update guide.

The Upgrade Path (Documented, Not Guessed)

Below is the standard documented Mastodon upgrade flow from docs.joinmastodon.org — the same flow the 5.0 beta notes build on. It is not 5.0-specific: read the 5.0 beta release notes on GitHub for the exact tag and version-specific steps, and treat those as authoritative.

Step 0: Back up before anything

# The standard documented backup set (docs: Migrating to a new machine)
sudo cp /var/lib/redis/dump.rdb /root/backup-rdb-$(date +%F)
sudo -u mastodon pg_dump mastodon_production > /root/backup-$(date +%F).psql
sudo -u mastodon cp /home/mastodon/live/.env.production /root/.env.production.$(date +%F)
# Local media only (not S3): also back up ~/live/public/system

Source installs: fetch, checkout, migrate, restart

su - mastodon
cd /home/mastodon/live
# Use the EXACT tag from the 5.0 beta release notes
git fetch --tags
git checkout <beta-tag-from-release-notes>
# Run the release-notes instructions FIRST, then:
SKIP_POST_DEPLOYMENT_MIGRATIONS=true RAILS_ENV=production bundle exec rails db:migrate
exit
systemctl restart mastodon-sidekiq
systemctl reload mastodon-web      # phased restart — zero downtime
systemctl restart mastodon-streaming
# Post-deployment migrations:
su - mastodon -c 'cd /home/mastodon/live && RAILS_ENV=production bundle exec rails db:migrate'

Per the docs, reload is a phased, zero-downtime restart — but restarting the streaming API disconnects all clients, which can spike load right after. If you proxy through Nginx and see gateway errors post-upgrade, our Nginx 502 Bad Gateway in Docker guide covers proxy-layer failures that masquerade as app problems.

Docker installs: pull, migrate, restart

cd /path/to/your/mastodon-compose
# Pin the EXACT beta tag from the release notes, not :latest
docker compose pull
docker compose run --rm -e SKIP_POST_DEPLOYMENT_MIGRATIONS=true web bundle exec rails db:migrate
docker compose up -d
docker compose run --rm web bundle exec rails db:migrate

⚠️ Beta — confirm in your staging instance. The exact beta tag, any requirement bumps, and whether 5.0 demands an Elasticsearch index rebuild are details only the official 5.0 beta release notes can settle. The commands above are the standard documented flow — your starting point, not a 5.0 guarantee.

After the Upgrade: 5 Fixes for the Usual Breakages

1. Stale interface / old CSS showing. Confirm asset precompilation completed, then hard-refresh (Ctrl+Shift+R). Behind a CDN or aggressive Nginx caching, purge cached assets — users on cached bundles see a broken old/new hybrid.

2. Streaming API dead after restart. The streaming service must be restarted on upgrade (documented), and every client reconnects at once. Check systemctl status mastodon-streaming — the reconnect storm is normal, a dead service is not.

3. Background jobs stuck. Sidekiq must be restarted after code changes (documented). If queues pile up, check logs for migration errors — a half-applied migration means restoring your pre-upgrade backup, not hand-editing the database.

4. Search misbehaving (Elasticsearch users). Past majors required rebuilding search indexes after migration. Whether 5.0 does is a 5.0-beta-notes question — check them.

5. "Where did my DMs / lists / quiet public go?" Not breakage — the redesign. Private mentions are Messages (Messages page only), lists are Custom feeds, "quiet public" is the "Discoverable in public feeds & search results" toggle. One pinned post saves a dozen tickets.

Should You Upgrade Now?

On staging: yes, today — that's what the beta is for, and the team wants Discourse feedback before stable. On production: wait. Betas ship regressions and the final notes aren't settled. When stable 5.0 lands in a few weeks: read the release notes, back up, re-test staging, then production.

✅ Verification note. Every feature, date, and step here is sourced from the official Mastodon blog, roadmap, or admin docs linked above. The 5.0 beta release notes (exact tag, requirement bumps, index-rebuild requirements) weren't accessible at writing time — every spot where they matter is flagged. Nothing was run against a live instance for this post; verify each command on your own staging system.

Frequently Asked Questions

When was the Mastodon 5.0 beta released for self-hosters?

Announced October 20, 2026: the first 5.0 beta invites server administrators to test before the stable release, expected in a few weeks.

Can I upgrade directly from Mastodon 4.7 to the 5.0 beta?

The docs advise deploying at least one release from every minor version series, and 4.7 is the latest minor series, so a direct upgrade is expected — but use the exact beta tag from the release notes on GitHub, and test on staging first.

Will Mastodon 5.0 break my custom CSS or theme tweaks?

Likely. The interface was rebuilt from the ground up on a newly tokenised design system, so re-verify custom styles on a staging instance before upgrading production.

Does Mastodon 5.0 require new Ruby, Node.js, PostgreSQL, or Redis versions?

Not confirmed. The upgrade docs point to each release's GitHub release notes for requirement changes, and the 5.0 beta notes were not yet accessible — read them before upgrading.

Does Mastodon 5.0 change federation or break compatibility with other servers?

Nothing in the official 5.0 announcements indicates federation protocol changes — the release is a web-interface and admin-tooling overhaul. Your server keeps federating with the rest of the fediverse as before.

What is the safest way to test the Mastodon 5.0 beta?

Clone your instance from a full backup (database, Redis dump, .env.production, uploaded media), upgrade the clone, and exercise the new composer, messages, and admin settings there. Report issues on the official Mastodon Discourse forum.