Pinterest Media Downloader (pinterest-dl)

English | 中文

Note

Version 1.0 is here! This release brings improved stability, better error handling, and enhanced testing (56 comprehensive tests). All existing code continues to work without any changes - we've maintained full backward compatibility.

This library facilitates the scraping and downloading of medias (including images and video stream) from Pinterest. Using reverse engineered Pinterest API and browser automation (Playwright by default, with Selenium as fallback), it enables users to extract images from a specified Pinterest URL and save them to a chosen directory.

It includes a CLI for direct usage and a Python API for programmatic access. The tool supports scraping medias from public and private boards and pins using browser cookies. It also allows users to save scraped URLs to a JSON file for future access.

Tip

If you are looking for a GUI version of this tool, check out pinterest-dl-gui. It provides a user-friendly interface for scraping and downloading media from Pinterest using the same underlying library. It could also serve as a reference for integrating the library into your own GUI application.

Warning

This project is independent and not affiliated with Pinterest. It's designed solely for educational purposes. Please be aware that automating the scraping of websites might conflict with their Terms of Service. The repository owner disclaims any liability for misuse of this tool. Use it responsibly and at your own legal risk.

Note

This project draws inspiration from pinterest-image-scraper.

Table of Contents

• Pinterest Media Downloader (pinterest-dl)
• Table of Contents
  • 🌟 Features
  • 🚩 Known Issues
  • 📋 Requirements
  • 📥 Installation
    • Using pip (Recommended)
    • Cloning from GitHub
  • 🚀 Quick Start
    • CLI Usage
    • Python API
  • 📚 Documentation
  • 🤝 Contributing
  • 📜 License

🌟 Features

• ✅ Scrape media directly from a Pinterest URL.
• ✅ Asynchronously download media from a list of URLs. (#1)
• ✅ Save scraped URLs to a JSON file for future access.
• ✅ Incognito mode to keep your scraping discrete.
• ✅ Access detailed output for effective debugging.
• ✅ Support for the Firefox browser.
• ✅ Insert alt text for media as metadata comment in the downloaded media for searchability.
• ✅ Optionally save alt text as a separate text file for each media. (#32)
• ✅ Scrape private boards and pins with browser cookies. (#20)
• ✅ Scrape media using reversed engineered Pinterest API. (This will be default behaviour. You can use webdriver by specifying --client chrome or --client firefox) (#21)
• ✅ Search for media on Pinterest using a query. (#23)
• ✅ Support multiple urls and queries in a single command.
• ✅ Support for batch processing of URLs and queries from files.
• ✅ Download video streams if available.
• ✅ Playwright support - faster and more reliable browser automation (default), with Selenium as fallback (--backend selenium).

🚩 Known Issues

• 🔲 Not able to scrape nested boards yet.

📋 Requirements

• Python 3.10 or newer
• (Optional) Playwright browsers: playwright install chromium or playwright install firefox
• (Optional) For Selenium backend: Chrome or Firefox browser with matching WebDriver
• (Optional) ffmpeg for video remuxing to MP4 (with --video option). If remux fails, automatically falls back to re-encoding. Use --skip-remux to download raw .ts files without ffmpeg.

📥 Installation

Using pip (Recommended)

pip install pinterest-dl

Cloning from GitHub

git clone https://github.com/sean1832/pinterest-dl.git
cd pinterest-dl
pip install .

🚀 Quick Start

CLI Usage

Scrape images from Pinterest using the command line:

# Scrape from a Pinterest board or pin
pinterest-dl scrape <url> -o output_folder -n 50

# Download videos as MP4 (requires ffmpeg)
pinterest-dl scrape <url> --video -o output_folder

# Download videos as raw .ts files (no ffmpeg needed)
pinterest-dl scrape <url> --video --skip-remux -o output_folder

# Search for images
pinterest-dl search "nature photography" -o output_folder -n 30

# Login to access private boards
pinterest-dl login -o cookies.json

📖 View Full CLI Documentation ->

Available commands: login, scrape, search, download

---

Python API

Use PinterestDL programmatically in your Python code:

from pinterest_dl import PinterestDL

# Quick scrape and download
images = PinterestDL.with_api().scrape_and_download(
    url="https://www.pinterest.com/pin/1234567",
    output_dir="images/art",
    num=30
)

# Search for images
images = PinterestDL.with_api().search_and_download(
    query="landscape art",
    output_dir="images/landscapes",
    num=50
)

📖 View Full API Documentation ->

Includes: High-level API, private board access, advanced scraping patterns

💡 See Complete Examples ->

Working examples covering:

• Basic scraping and downloading
• Search functionality
• Cookie authentication for private boards
• Video downloading
• Advanced control with lower-level API
• Debug mode and troubleshooting

---

📚 Documentation

• CLI Guide - Complete command-line interface documentation
• Python API Guide - Programmatic usage examples and patterns
• Contributing Guidelines - How to contribute to the project

🤝 Contributing

We welcome contributions! Please see CONTRIBUTING.md for:

• Code of Conduct
• Commit message guidelines (semantic commits)
• Pull request process

📜 License

This project is licensed under the Apache 2.0 License - see the LICENSE file for details.

---

Made with ❤️ by sean1832

Note: This project is not affiliated with Pinterest. All trademarks are property of their respective owners.