Mastodon v4.0.0 Upgrade [v4.0.2]

Mastodon v4.0.0 Upgrade [v4.0.2]

What's new in Mastodon v4.0.0, and how do you upgrade? Read on for the headline features and to see how to get started with Mastodon v4.0.0.

I don't think I will post for every single Mastodon upgrade, but the stable version that most people who recently joined found themselves using was v3.5.3. Release candidate versions have been running on a few servers, but now that version 4.0.0 4.0.2 has been released, some new features are available to an increasing number of instances.

Edit - 16/11/2022: Mastodon v4.0.2 was released not long after v4.0.0. Instructions have been updated accordingly.

TL;DR: If you don't want to read me witter on about the new features, the upgrade procedure is below.

Release v4.0.2 · mastodon/mastodon
ChangelogFixed Fix wrong color on mentions hidden behind content warning in web UI (Gargron)Fix filters from other users being used in the streaming service (ClearlyClaire)Fix unsafe-eval being...

The full changelog is available above, but there are a few headline acts:

Post Editing

The oft-rumoured, sometimes tested Twitter feature is now available to anyone using the latest Mastodon version. Just click the ellipsis at the bottom-right of a post and choose edit.

The more interesting thing is how this edit is reflected to others who had already interacted with your post: they get a notification to say you've edited it, which gives them a chance to change their own reaction - the whole thing seems pretty seamless (so far).

Screenshot showing the 'Edit' option on a Mastodon post

Follow Hashtags

Sometimes, you might not know who to follow. This is especially true for those who have recently migrated across from Twitter. Well, now you can follow a hashtag. Just search for it in the top left, choose it from the results, then click the icon to the top-right of the first post.

Screenshot showing the location of the follow icon when trying to follow a hashtag in Mastodon

Translate Posts

Server admins will be able to integrate either LibreTranslate or DeepL to translate posts for users on-demand (and then cache them for future users). There will be some kind of cost associated with these services, but this is a great feature to make content accessible to more regions, and particularly useful if you run an instance will users from a few different countries.

Automate Cleanup Tasks

The way that Mastodon instances communicate means that a lot of data is cached, especially media content. This can add up to a lot of storage, so the previous advice was to run some commands (at least once per 24hours) to remove cached data older than one week, for example.

Going into the admin section (admin/settings/content_retention) gives fields where this can now be set in the front end, saving the need to find the tootctl command and add it to crontab.

Screenshot show the 'content retention' pane in the Mastodon instance admin section

Admin Webhooks

You can now make your Mastodon instance trigger a webhook when a couple of events occur:

  • New user signup
  • New report

How you use it will vary, but I can forsee piping this information into Home Assistant...

+ So much more:

I'm not going to go over every feature. The list of additions and changes is extensive, to say the least.

More importantly, if you're running v3.5.3, how do you upgrade?

Non-Docker Upgrade Procedure

The first step is to backup your instance. Ideally, after backing things up, you should copy the files off to another system, in case something catastrophic happens (you should be doing this anyway. Regularly).

sudo cp /var/lib/redis/dump.rdb /tmp/backup.rdb

sudo su - mastodon

pg_dump mastodon_production > /tmp/backup.psqld
cp live/.env.production /tmp/.env.production

If your image/uploaded content is stored locally, you should also backup the public/system directory within the Mastodon live folder, too. If you're using S3, you don't need to worry.

The Mastodon Docs site has some good information on backing things up.

Once backed up, you can run the following commands:

sudo su - mastodon

cd live
RUBY_CONFIGURE_OPTS=--with-jemalloc rbenv install 3.0.4
rbenv global 3.0.4

git fetch && git checkout v4.0.2
bundle install
yarn install

SKIP_POST_DEPLOYMENT_MIGRATIONS=true RAILS_ENV=production bundle exec rails db:migrate
RAILS_ENV=production bundle exec rails assets:precompile

sudo systemctl restart 'mastodon*'
sudo su - mastodon
cd live && RAILS_ENV=production bundle exec rails db:migrate

sudo systemctl restart 'mastodon*'

Edit: version in the block above has been changed to v4.0.2.

Note, the above commands are a slightly-expanded upon set from the v4.0.0RC1 notes:

Release v4.0.0rc1 · mastodon/mastodon
Note: This is a release candidate. It is intended to be stable, but not guaranteed. Upgrade overviewThis release contains upgrade notes that deviate from the norm:ℹ️ Requires two-step database m...

After the final restart, everything worked fine, except for seeing a 500 Internal Server Error message. The v4 release did have a note:

"Some server settings, like thumbnail, short description, and so on, changed and may need to be looked at"

Going into the admin section & branding (/admin/settings/branding), and removing then re-uploading the instance banner image seems to fix the issue.

I can't comment on the procedure for Docker-based installations, but the notes on the above 'rc1' page covered this method.


Nothing should go wrong, of course (and you did remember to take that backup, right?), but here are some potential pitfalls:

Compilation Failed

test@testbits:~/live$ RAILS_ENV=production bundle exec rails assets:precompile
yarn install v1.22.19
[1/6] Validating package.json...
[2/6] Resolving packages...
[3/6] Fetching packages...
[4/6] Linking dependencies...
warning Workspaces can only be enabled in private projects.
[5/6] Building fresh packages...
[6/6] Cleaning modules...
Done in 21.87s.
Compilation failed:

Compiling the assets can fail if you're running on a system with limited RAM. If you have 2gig or less, check the available swap space before starting, and if necessary, add some more.

Check to see if you have any by running free -h - look on the 'Swap' row to see the total. If it's 0, and you want to add some, run the following commands (substituting the '4G' for your desired amount of swap space):

sudo fallocate -l 4G /swapfile
sudo chmod 600 /swapfile
sudo mkswap /swapfile
sudo swapon /swapfile

Once done, you can confirm with free -h again, then retry the asset compile with:

sudo su - mastodon
cd live
RAILS_ENV=production bundle exec rails assets:clobber assets:precompile
Even though compilation previously failed, the system can think that it's already been done. Adding in assets:clobber before assets:precompile clears the previous files and forces a fresh compile.

Other Edits

This post has gained a surprising amount of traction, and I've had some great responses.

Daniel (below) pointed out that wherever I used the command sudo systemctl restart mastodon*, it would be better with sudo systemctl restart 'mastodon*'.

With most shells, if there happens to be files that start with "mastodon” in the current directory, the expression without the quotes will glob expand to those file names and the actual service names won’t be picked up.

Daniel Norton (not parody) ( With most shells, if there happens to be files that start with “mastodon” in the current directory, the expression without the quotes will glob expand to those file names and the actual service names won’t be picked up.

I'd love to know if this helped, or if I'm missing any information in the comments, or over at or @techbitsio.

Great! Next, complete checkout for full access to
Welcome back! You've successfully signed in
You've successfully subscribed to
Success! Your account is fully activated, you now have access to all content
Success! Your billing info has been updated
Your billing was not updated