0.7.3 • Public • Published

Tweet To Toot – export your Twitter threads to Mastodon

You want to break free of the site formerly known as Twitter but do not want to lose your numerous, ongoing, carefully maintained, years-long threads?

Tweet-to-Toot is for your: grab an archive of your Twitter account, republish the threads your want on Mastodon and start anew.

Under the hood is a heavy fork of Tweetback and a client for the Mastodon API.

it works with pictures and videos. It even flattens branching threads (meaning: if you replied several times to the same tweet, all replies with be inserted in the main thread).


  • Install Node, v18 or 19. NVM advised if it's not your typical Node environnment.
  • In your terminal, go to the folder of your archive.
  • Run npm install tweet-to-toot.
  • Grab a Mastodon API token by following these instructions.
  • Add the token and the URL of you instance as environnment variables. The simplest way is to put them in a file named .env (no extension) at the root of your project. See .env.sample.


npx totoot --ids 0000000000 [optional parameters]

Full examples:

  • npx totoot --ids 1157670494390378498 --intro "imported thread, started in 2019 on the Other Site" --dry-run

  • npx totoot --ids 1157670494390378498 791709895083102209 --wait 10 --lang en


--ids: One or several space-separated IDs of twitter messages. These ID can be found at the end of their URL, after "status/". Tweet-to-Toot will use these as a starting poing and find more recent replies in your archive. So choose the oldest message in your thread.

--intro: Optional short text in quotes. Append a message at the beginning of your Mastodon thread.

--wait: Number of seconds. Waiting period between each request to Mastodon. Default : one second.

--dry-run: Show thread without publishing it.

--merge: Default to false. Defines behavior for quoted tweets of yourself. If false, it will keep the quote as a link to If true, it will merge the quoting and the quoted message. The URL to the quoted message is preserved.

--concatWith: Optional Mastodon message id. If provided, the thread will be posted as a continuation of this message. Useful if you want merge threads.

--lang: Optional. Set language for the Mastodon thread. Use a 639-1 string ("en" for english, "fr" for french...).

Note on languages:

  • By default, we use the attribute present in each message of your Twitter archive, because it seems good at guessing languages (or at least western mainstream ones). So it's useful for preserving multi-lingual threads.
  • The priority order is: the --lang parameter, then the attribute from your archive, then the parameter from your Mastodon account.


  • Twitter can show threads with deleted messages in the middle. We can't. Workaround: Use it twice and the second time specifiy a concatWith option.
  • Use wait generously. With media, the default rate limit of your instance can be quickly reached.
  • Mastodon doesn't officially support a way for instances to customize a limit to message length. So this tool assumes a default length of 500 caracters. When used with the --merge parameter, it can result in truncated messages.

Package Sidebar


npm i tweet-to-toot

Weekly Downloads






Unpacked Size

114 kB

Total Files


Last publish


  • baptiste-roullin