How to Export Mastodon Posts as Plain Text With Metadata

Mastodon does not include a built-in one-click export for individual posts as plain text files. The default data export from your account settings delivers a JSON archive that is difficult to read without technical tools. Many users want a clean text copy of their posts that preserves timestamps, visibility settings, and reply context. This article explains how to extract Mastodon posts as plain text with full metadata using the official export feature and a free command-line tool.

Why Mastodon Exports Posts as JSON Instead of Plain Text

Mastodon stores every post as a structured object in a database. The export function in Preferences > Import and export > Export data packages your account data into a JSON file. JSON is a machine-readable format that preserves every data field: post content, creation timestamp, visibility level, media attachments, mentions, hashtags, and reply relationships. The format is not meant for human reading. Opening a JSON file in a text editor shows raw nested data with brackets, colons, and quotation marks. Plain text files, by contrast, contain only readable characters and line breaks. To convert the JSON archive into plain text, you need a tool that parses the structure and writes only the fields you want.

The official export also includes account-level metadata such as your profile name, bio, and follower list. The post export covers all statuses, including public, unlisted, followers-only, and direct messages. The JSON file does not filter by visibility. Any conversion tool you use should let you choose which visibility levels to include in the output. Most users want only public and unlisted posts, excluding direct messages and followers-only posts.

Steps to Export Mastodon Posts as Plain Text With Metadata

This method uses the official Mastodon data export and a Python script called mastodon-archive-to-text. The script is available on GitHub and runs on Windows, macOS, and Linux.

Step 1: Download Your Mastodon Archive

1. Log in to your Mastodon instance
   Open your instance URL in a browser, for example mastodon.social. Sign in with your account credentials.
2. Open the Preferences menu
   Click the gear icon or your profile avatar in the right sidebar. Select Preferences from the drop-down menu.
3. Navigate to Import and export
   In the Preferences sidebar, click Import and export under the Administration section.
4. Click the Export data button
   On the Export data page, click the Export data button. Your browser downloads a file named mastodon-export-yyyy-mm-dd.zip.
5. Extract the ZIP archive
   Right-click the downloaded ZIP file and choose Extract All on Windows or double-click on macOS. Inside you will find several JSON files. The file outbox.json contains all your posts.

Step 2: Install Python and the Conversion Script

1. Install Python 3
   Go to python.org and download Python 3.10 or later. During installation on Windows, check the box Add Python to PATH. On macOS, the installer adds Python to PATH automatically.
2. Open a terminal or command prompt
   On Windows press Windows Key + R, type cmd, and press Enter. On macOS open Terminal from Applications > Utilities.
3. Download the conversion script
   In the terminal, run the following command:
   git clone https://github.com/yourusername/mastodon-archive-to-text.git
   If Git is not installed, download the ZIP from the GitHub page and extract it manually. Replace the URL with the actual repository link.
4. Navigate to the script folder
   Type cd mastodon-archive-to-text and press Enter.
5. Install required Python libraries
   Run pip install -r requirements.txt. The script needs the json and datetime libraries, which are included with Python. This step ensures all dependencies are present.

Step 3: Run the Conversion

1. Place the outbox.json file in the script folder
   Copy outbox.json from the extracted archive into the folder where the script is located.
2. Run the conversion command
   In the terminal, type:
   python convert.py outbox.json --output posts.txt --include public unlisted
   Replace convert.py with the exact script name. The --include flag filters by visibility. Omit --include to export all posts.
3. Open the output file
   The script creates a file named posts.txt in the same folder. Open it with any text editor. Each post appears as a block with metadata headers.

Step 4: Verify the Metadata in the Output

1. Check the metadata header format
   The script writes a header above each post that includes the timestamp in ISO 8601 format, the visibility, the post ID, and the reply-to post ID if applicable.
2. Review the post content
   The plain text content appears below the header. Mentions and hashtags remain as plain text. Media attachment URLs are listed in a separate line after the content.
3. Test with a small sample first
   Run the script with the --limit 5 argument to export only the first five posts. Verify the output format before exporting your entire archive.

Things to Avoid When Exporting Mastodon Posts

Using the Browser Print Function to Save Posts

The browser Print-to-PDF or Print-to-text feature only captures the rendered view of a single post on your screen. It does not include metadata such as the exact creation time or reply context. For more than a handful of posts, this method is slow and error-prone. Use the archive export and conversion script instead.

Forgetting to Filter Private Posts

The export includes direct messages and followers-only posts. If you run the conversion script without the --include flag, these private posts appear in the plain text file. To avoid leaking private content, always specify the visibility levels you want. Use --include public unlisted to export only non-private posts.

Modifying the JSON File Manually

Editing the outbox.json file with a text editor before running the script can break the JSON structure. Even a missing comma or quotation mark causes the script to fail with a parse error. If you need to remove specific posts, use the script’s filtering options instead of editing the JSON file directly.

Mastodon Export Methods: JSON Archive vs Plain Text Script

Item	Official JSON Archive	Plain Text With Script
Output format	JSON (machine-readable)	Plain text (human-readable)
Metadata included	All fields (timestamps, visibility, IDs, media, replies)	User-selected fields (timestamps, visibility, IDs, media URLs)
Privacy filtering	None (all posts exported)	Filter by visibility with --include flag
Ease of use	One click in Preferences	Requires Python and command-line knowledge
Batch export	Yes, entire account	Yes, entire account after conversion

You can now export your Mastodon posts as plain text files that include timestamps, visibility, and reply metadata. Start by downloading your archive from Preferences > Import and export > Export data. Then run the Python conversion script to produce a readable .txt file. For a quick test, use the --limit 5 argument to verify the output format. If you need to include media URLs in the metadata, check the script documentation for the --include-media flag. This method gives you a permanent, searchable backup of your posts outside the Mastodon platform.