pinterest-dl 1.1.2

An unofficial Pinterest image downloader

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. (Supported since #69)

📋 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.
• (Optional) For image resolution detection and pruning, requires pillow library. Install with pip install pinterest-dl[image].
• (Optional) For embedding alt text as metadata comment, requires pyexiv2 library. Install with pip install pinterest-dl[exif].

📥 Installation

Using pip (Recommended)

Basic installation (core functionality only):

pip install pinterest-dl

With optional dependencies:

# With image operations (resolution detection, pruning)
pip install pinterest-dl[image]

# With EXIF metadata support (embed alt text as metadata)
pip install pinterest-dl[exif]

# With all image/metadata features
pip install pinterest-dl[metadata]

# For development (includes testing tools)
pip install pinterest-dl[dev,all]

[!NOTE] Optional Dependencies:

• image - Installs Pillow for image resolution detection and pruning features
• exif - Installs pyexiv2 for EXIF metadata embedding (alt text as metadata comment)
• metadata - Installs both Pillow and pyexiv2
• all - Installs all optional dependencies (Currently Pillow and pyexiv2)
• dev - Installs testing tools (pytest, pytest-mock)

Without optional dependencies, you can still scrape and download images, but features requiring image analysis (resolution detection, metadata embedding) will raise an informative error.

Cloning from GitHub

git clone https://github.com/sean1832/pinterest-dl.git
cd pinterest-dl
pip install .
# Or with optional dependencies
pip install .[all]

🚀 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.