Medium Post Downloader

July 23, 2025 · View on GitHub

A comprehensive tool to organize Medium export archives and download all associated images from Medium's CDN, creating a complete, self-contained archive of your blog posts.

Why This Tool?

Medium's export feature only provides the text content of your posts, leaving out the images that are hosted on their CDN. This is frustrating for content creators who want a complete backup of their work, especially when images are a core part of their posts.

This tool solves that problem by:

  • 📁 Organizing posts by year for better structure
  • 🖼️ Downloading all images from Medium's CDN
  • 🔗 Updating HTML to use local image paths
  • 🧹 Filtering out comments/responses from full articles
  • 📦 Creating a complete, portable archive

Features

  • Smart Organization: Automatically organizes posts by publication year
  • Image Download: Downloads all images from Medium's CDN (cdn-images-1.medium.com, cdn-images-2.medium.com, miro.medium.com)
  • HTML Updates: Updates image references to use local paths
  • Comment Filtering: Separates full articles from comments/responses
  • Resume Support: Skips already processed posts
  • Respectful Downloading: Configurable delays between downloads
  • Cross-Platform: Works on Windows, macOS, and Linux

Installation

  1. Clone this repository:
git clone https://github.com/danielrosehill/Medium-Post-Downloader.git
cd Medium-Post-Downloader
  1. Create a virtual environment:
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate
  1. Install dependencies:
pip install -r requirements.txt

Usage

Step 1: Export Your Medium Data

  1. Go to Medium Settings → Account → Download your information
  2. Wait for the email with your export link
  3. Download and extract the ZIP file

Step 2: (Optional) Clean Comments/Responses

First, run the cleaner to separate full articles from comments:

# Dry run to see what would be filtered
python medium_post_cleaner.py --input /path/to/medium-export

# Actually move comments to excluded folder
python medium_post_cleaner.py --input /path/to/medium-export --execute

Step 3: Download and Organize Posts

Run the main downloader:

python medium_post_downloader.py --input /path/to/medium-export --output /path/to/organized-posts

Command Line Options

Medium Post Downloader

python medium_post_downloader.py [OPTIONS]

Required:
  --input, -i PATH    Path to extracted Medium export directory
  --output, -o PATH   Path where organized posts should be saved

Optional:
  --delay SECONDS     Delay between image downloads (default: 0.5)
  --help             Show help message

Medium Post Cleaner

python medium_post_cleaner.py [OPTIONS]

Required:
  --input, -i PATH    Path to extracted Medium export directory

Optional:
  --min-words COUNT   Minimum word count for full articles (default: 100)
  --execute          Actually move files (default: dry run)
  --help             Show help message

Output Structure

After processing, your posts will be organized like this:

organized-posts/
├── 2024/
│   ├── My-Latest-Article/
│   │   ├── post.html
│   │   ├── image1.jpg
│   │   └── image2.png
│   └── Another-Great-Post/
│       ├── post.html
│       └── featured-image.jpg
├── 2023/
│   └── ...
└── excluded_posts/  # Comments/responses (if cleaner was used)
    ├── short-comment.html
    └── brief-response.html

Examples

Basic Usage

# Process Medium export with default settings
python medium_post_downloader.py --input ~/Downloads/medium-export --output ~/my-medium-archive

With Custom Delay

# Use 1-second delay between downloads (more respectful to servers)
python medium_post_downloader.py --input ~/Downloads/medium-export --output ~/my-medium-archive --delay 1.0

Complete Workflow

# 1. Clean comments first (dry run)
python medium_post_cleaner.py --input ~/Downloads/medium-export

# 2. Actually move comments
python medium_post_cleaner.py --input ~/Downloads/medium-export --execute

# 3. Download and organize posts
python medium_post_downloader.py --input ~/Downloads/medium-export --output ~/my-medium-archive

How It Works

  1. Discovery: Automatically finds the posts directory in your Medium export
  2. Analysis: Parses HTML files to extract dates and organize by year
  3. Image Detection: Scans HTML for Medium CDN image URLs
  4. Download: Downloads images with respectful delays
  5. Update: Modifies HTML to reference local image files
  6. Organization: Creates clean folder structure with one folder per post

Troubleshooting

"Could not find posts directory"

  • Ensure you've extracted the Medium export ZIP file
  • Check that the directory contains HTML files
  • Try specifying the exact posts directory path

Images not downloading

  • Check your internet connection
  • Some images may have been removed from Medium's CDN
  • Increase the delay if you're getting rate limited

HTML files not found

  • Make sure you downloaded the full Medium export (not just settings)
  • Check that the export completed successfully

Contributing

Contributions are welcome! Please feel free to:

  • Report bugs
  • Suggest features
  • Submit pull requests
  • Improve documentation

License

This project is open source and available under the MIT License.

Acknowledgments

  • Built to solve the frustrating problem of incomplete Medium exports
  • Inspired by the need for complete, portable blog archives
  • Designed to be respectful to Medium's servers while providing full functionality