# Pinterest Media Downloader (pinterest-dl)
[](https://pypi.org/project/pinterest-dl/)
[](https://pypi.org/project/pinterest-dl/)
[](https://github.com/sean1832/pinterest-dl/blob/main/LICENSE)
[](https://pepy.tech/project/pinterest-dl)
<a href="https://www.buymeacoffee.com/zekezhang" target="_blank"><img src="https://cdn.buymeacoffee.com/buttons/v2/default-blue.png" alt="Buy Me A Coffee" style="height: 40px !important;width: 145px !important;" ></a>
**English | [δΈζ](README_CN.md)**
This library facilitates the scraping and downloading of medias (including images and video stream) from [Pinterest](https://pinterest.com). Using reverse engineered Pinterest API and [Selenium](https://selenium.dev) for automation, it enables users to extract images from a specified Pinterest URL and save them to a chosen directory.
It includes a [CLI](#-cli-usage) for direct usage and a [Python API](#οΈ-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](https://github.com/sean1832/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](https://developers.pinterest.com/terms/). 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](https://github.com/xjdeng/pinterest-image-scraper).
# Table of Contents
- [Pinterest Media Downloader (pinterest-dl)](#pinterest-media-downloader-pinterest-dl)
- [Table of Contents](#table-of-contents)
- [π Features](#-features)
- [π© Known Issues](#-known-issues)
- [π Requirements](#-requirements)
- [π₯ Installation](#-installation)
- [Using pip (Recommended)](#using-pip-recommended)
- [Cloning from GitHub](#cloning-from-github)
- [π CLI-Usage](#-cli-usage)
- [General Command Structure](#general-command-structure)
- [Commands](#commands)
- [1. Login](#1-login)
- [2. Scrape](#2-scrape)
- [3. Search](#3-search)
- [4. Download](#4-download)
- [π οΈ Python API](#οΈ-python-api)
- [1. High-level Scrape and Download](#1-high-level-scrape-and-download)
- [1a. Scrape with Cookies for Private Boards](#1a-scrape-with-cookies-for-private-boards)
- [2. Detailed Scraping with Lower-Level Control](#2-detailed-scraping-with-lower-level-control)
- [2a. With API](#2a-with-api)
- [Scrape Media](#scrape-media)
- [Search Media](#search-media)
- [2b. With Browser](#2b-with-browser)
- [π€ Contributing](#-contributing)
- [π License](#-license)
## π Features
- β
Scrape media directly from a Pinterest URL.
- β
Asynchronously download media from a list of URLs. ([#1](https://github.com/sean1832/pinterest-dl/pull/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](https://github.com/sean1832/pinterest-dl/pull/32))
- β
Scrape private boards and pins with browser cookies. ([#20](https://github.com/sean1832/pinterest-dl/pull/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](https://github.com/sean1832/pinterest-dl/pull/21))
- β
Search for media on Pinterest using a query. ([#23](https://github.com/sean1832/pinterest-dl/pull/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.
## π© Known Issues
- π² Not yet implement testing.
- π² Not sorely tested on ~~Linux and~~ Mac. Please create an [Issue](https://github.com/sean1832/pinterest-dl/issues) to report any bugs.
## π Requirements
- Python 3.10 or newer
- (Optional) Chrome or Firefox browser
- [ffmpeg](https://ffmpeg.org/) added to your PATH for video stream downloading (with `--video` option)
## π₯ Installation
### Using pip (Recommended)
```bash
pip install pinterest-dl
```
### Cloning from GitHub
```bash
git clone https://github.com/sean1832/pinterest-dl.git
cd pinterest-dl
pip install .
```
## π CLI-Usage
### General Command Structure
```bash
pinterest-dl [command] [options]
```
| Command | Description |
| ------------------------- | ---------------------------------------------------------------------------------- |
| [`login`](#1-login) | Login to Pinterest to obtain browser cookies for scraping private boards and pins. |
| [`scrape`](#2-scrape) | Scrape images from a Pinterest URL. |
| [`search`](#3-search) | Search for images on Pinterest using a query. |
| [`download`](#4-download) | Download images from a list of URLs provided in a JSON file. |
---
### Commands
#### 1. Login
Authenticate to Pinterest and save browser cookies for private boards/pins.
```bash
pinterest-dl login [options]
```
| Options | Description | Default |
| --------------------------- | ------------------------- | -------------- |
| `-o`, `--output [file]` | Path to save cookies file | `cookies.json` |
| `--client [chrome/firefox]` | Browser client to use | `chrome` |
| `--headful` | Show browser window | - |
| `--incognito` | Use incognito mode | - |
| `--verbose` | Enable debug output | - |
> [!TIP]
> After running `login`, youβll be prompted for your Pinterest email/password. Cookies are then saved to the specified file.
---
#### 2. Scrape
Download images from a Pin, Board URL, or a list of URLs.
```bash
# Single or multiple URLs:
pinterest-dl scrape <url1> <url2> β¦
# From one or more files (one URL per line):
pinterest-dl scrape -f urls.txt [options]
pinterest-dl scrape -f urls1.txt -f urls2.txt [options]
# From stdin:
cat urls.txt | pinterest-dl scrape -f - [options]
```
| Options | Description | Default |
| ------------------------------------ | -------------------------------------------------------- | -------------- |
| `-f`, `--file [file]` | Path to file with URLs (one per line); use `-` for stdin | β |
| `<url>` | One or more Pinterest URLs | β |
| `-o`, `--output [directory]` | Directory to save images (stdout if omitted) | β |
| `-c`, `--cookies [file]` | Path to cookies file (for private content) | `cookies.json` |
| `-n`, `--num [number]` | Maximum images to download | `100` |
| `-r`, `--resolution [WxH]` | Minimum image resolution (e.g. `512x512`) | β |
| `--video` | Download video stream (if available) | β |
| `--timeout [seconds]` | Request timeout | `3` |
| `--delay [seconds]` | Delay between requests | `0.2` |
| `--cache [path]` | Save scraped URLs to JSON | β |
| `--caption [txt/json/metadata/none]` | Caption format: `txt`, `json`, `metadata`, or `none` | `none` |
| `--ensure-cap` | Require alt text on every image | β |
| `--client [api/chrome/firefox]` | Scraper backend | `api` |
| `--headful` | Show browser window (chrome/firefox only) | β |
| `--incognito` | Use incognito mode (chrome/firefox only) | β |
| `--verbose` | Enable debug output | β |
---
#### 3. Search
Find and download images via a search query (API mode only), or from URL-lists in files.
```bash
# Simple query:
pinterest-dl search <query1> <query2> ... [options]
# From one or more files:
pinterest-dl search -f queries.txt [options]
pinterest-dl search -f q1.txt -f q2.txt [options]
# From stdin:
cat queries.txt | pinterest-dl search -f - [options]
```
| Options | Description | Default |
| ------------------------------------ | ----------------------------------------------------------- | -------------- |
| `-f`, `--file [file]` | Path to file with queries (one per line); use `-` for stdin | β |
| `<query>` | One or more search terms | β |
| `-o`, `--output [directory]` | Directory to save images (stdout if omitted) | β |
| `-c`, `--cookies [file]` | Path to cookies file | `cookies.json` |
| `-n`, `--num [number]` | Maximum images to download | `100` |
| `-r`, `--resolution [WxH]` | Minimum image resolution | β |
| `--video` | Download video stream (if available) | β |
| `--timeout [seconds]` | Request timeout | `3` |
| `--delay [seconds]` | Delay between requests | `0.2` |
| `--cache [path]` | Save results to JSON | β |
| `--caption [txt/json/metadata/none]` | Caption format | `none` |
| `--ensure-cap` | Require alt text on every image | β |
| `--verbose` | Enable debug output | β |
---
#### 4. Download
Fetch images from a previously saved cache file.
```bash
pinterest-dl download <cache.json> [options]
```
| Options | Description | Default |
| -------------------------- | ------------------------ | ------------------- |
| `-o`, `--output [dir]` | Directory to save images | `./<json_filename>` |
| `-r`, `--resolution [WxH]` | Minimum image resolution | - |
| `--verbose` | Enable debug output | - |
## π οΈ Python API
You can also use the `PinterestDL` class directly in your Python code to scrape and download images programmatically.
### 1. High-level Scrape and Download
This example shows how to **scrape** and download images from a Pinterest URL in one step.
```python
from pinterest_dl import PinterestDL
# Initialize and run the Pinterest image downloader with specified settings
images = PinterestDL.with_api(
timeout=3, # Timeout in seconds for each request (default: 3)
verbose=False, # Enable detailed logging for debugging (default: False)
ensure_alt=True, # Ensure every image has alt text (default: False)
).scrape_and_download(
url="https://www.pinterest.com/pin/1234567", # Pinterest URL to scrape
output_dir="images/art", # Directory to save downloaded images
num=30, # Max number of images to download
download_streams=True, # Download video streams if available (default: False)
min_resolution=(512, 512), # Minimum resolution for images (width, height) (default: None)
cache_path="art.json", # Path to cache scraped data as json (default: None)
caption="txt", # Caption format for downloaded images: 'txt' for alt text in separate files, 'json' for full image data in seperate file, 'metadata' embeds in image files, 'none' for no captions
delay=0.4, # Delay between requests (default: 0.2)
)
```
This example shows how to **search** with query and download images from a Pinterest URL in one step.
```python
from pinterest_dl import PinterestDL
# Initialize and run the Pinterest image downloader with specified settings
# `search_and_download` is only available in API mode
images = PinterestDL.with_api(
timeout=3, # Timeout in seconds for each request (default: 3)
verbose=False, # Enable detailed logging for debugging (default: False)
ensure_alt=True, # Ensure every image has alt text (default: False)
).search_and_download(
query="art", # Pinterest search query
output_dir="images/art", # Directory to save downloaded images
num=30, # Max number of images to download
download_streams=True, # Download video stream if available (default: False)
min_resolution=(512, 512), # Minimum resolution for images (width, height) (default: None)
cache_path="art.json", # Path to cache scraped data as json (default: None)
caption="txt", # Caption format for downloaded images: 'txt' for alt text in separate files, 'json' for full image data in seperate file, 'metadata' embeds in image files, 'none' for no captions
delay=0.4, # Delay between requests (default: 0.2)
)
```
#### 1a. Scrape with Cookies for Private Boards
**2a. Obtain cookies**
You need to first log in to Pinterest to obtain browser cookies for scraping private boards and pins.
```python
import os
import json
from pinterest_dl import PinterestDL
# Make sure you don't expose your password in the code.
email = input("Enter Pinterest email: ")
password = os.getenv("PINTEREST_PASSWORD")
# Initialize browser and login to Pinterest
cookies = PinterestDL.with_browser(
browser_type="chrome",
headless=True,
).login(email, password).get_cookies(
after_sec=7, # Time to wait before capturing cookies. Login may take time.
)
# Save cookies to a file
with open("cookies.json", "w") as f:
json.dump(cookies, f, indent=4)
```
**2b. Scrape with cookies**
After obtaining cookies, you can use them to scrape private boards and pins.
```python
import json
from pinterest_dl import PinterestDL
# Load cookies from a file
with open("cookies.json", "r") as f:
cookies = json.load(f)
# Initialize and run the Pinterest image downloader with specified settings
images = (
PinterestDL.with_api()
.with_cookies(
cookies, # cookies in selenium format
)
.scrape_and_download(
url="https://www.pinterest.com/pin/1234567", # Assume this is a private board URL
output_dir="images/art", # Directory to save downloaded images
num=30, # Max number of images to download
)
)
```
### 2. Detailed Scraping with Lower-Level Control
Use this example if you need more granular control over scraping and downloading images.
#### 2a. With API
##### Scrape Media
```python
import json
from pinterest_dl import PinterestDL
# 1. Initialize PinterestDL with API and scrape media
scraped_medias = PinterestDL.with_api().scrape(
url="https://www.pinterest.com/pin/1234567", # URL of the Pinterest page
num=30, # Maximum number of images to scrape
min_resolution=(512, 512), # <- Only available to set in the API. Browser mode will have to pruned after download.
)
# 2. Download Media
# Download media to a specified directory
output_dir = "images/art"
downloaded_items = PinterestDL.download_media(
media=scraped_medias,
output_dir=output_dir,
download_streams=True # Download video streams if available; otherwise download images only.
)
# 3. Save Scraped Data to JSON (Optional)
# Convert scraped data into a dictionary and save it to a JSON file for future access
media_data = [media.to_dict() for media in scraped_medias]
with open("art.json", "w") as f:
json.dump(media_data, f, indent=4)
# 4. Add Alt Text as Metadata (Optional)
# Extract `alt` text from media and set it as metadata in the downloaded files
PinterestDL.add_captions_to_meta(images=downloaded_items)
# 4. Add Alt Text as text file (Optional)
# Extract `alt` text from media and save it as a text file in the downloaded directory
PinterestDL.add_captions_to_file(downloaded_items, output_dir, extension="txt")
```
##### Search Media
```python
import json
from pinterest_dl import PinterestDL
# 1. Initialize PinterestDL with API.
scraped_medias = PinterestDL.with_api().search(
query="art", # Search query for Pinterest
num=30, # Maximum number of images to scrape
min_resolution=(512, 512), # Minimum resolution for images
delay=0.4, # Delay between requests (default: 0.2)
)
# ... (Same as above)
```
#### 2b. With Browser
```python
import json
from pinterest_dl import PinterestDL
# 1. Initialize PinterestDL with API.
scraped_medias = PinterestDL.with_browser(
browser_type="chrome", # Browser type to use ('chrome' or 'firefox')
headless=True, # Run browser in headless mode
ensure_alt=True, # Ensure every image has alt text (default: False)
).scrape(
url="https://www.pinterest.com/pin/1234567", # URL of the Pinterest page
num=30, # Maximum number of images to scrape
)
# 2. Save Scraped Data to JSON
# Convert scraped data into a dictionary and save it to a JSON file for future access
media_data = [media.to_dict() for media in scraped_medias]
with open("art.json", "w") as f:
json.dump(media_data, f, indent=4)
# 3. Download Media
# Download media to a specified directory
output_dir = "images/art"
downloaded_media = PinterestDL.download_media(
media=scraped_medias,
output_dir=output_dir,
download_streams=False, # <- browser mode does not support video streams yet
)
# 4. Prune Media by Resolution (Optional)
# Remove media that do not meet the minimum resolution criteria
kept_media = PinterestDL.prune_images(images=downloaded_media, min_resolution=(200, 200))
# 5. Add Alt Text as Metadata (Optional)
# Extract `alt` text from media and set it as metadata in the downloaded files
PinterestDL.add_captions_to_meta(images=kept_media)
# 6. Add Alt Text as text file (Optional)
# Extract `alt` text from media and save it as a text file in the downloaded directory
PinterestDL.add_captions_to_file(kept_media, output_dir, extension="txt")
```
## π€ Contributing
Contributions are welcome! Please check the [Contribution Guidelines](CONTRIBUTING.md) before submitting a pull request.
## π License
[Apache License 2.0](LICENSE)
Raw data
{
"_id": null,
"home_page": null,
"name": "pinterest-dl",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": null,
"keywords": "pinterest, image downloader, web scraping",
"author": null,
"author_email": "sean1832 <dev@zekezhang.com>",
"download_url": "https://files.pythonhosted.org/packages/ad/62/7ae7d13260c76737c210c000f31b21ec2db6dbf13deb2658ee4b3474397e/pinterest_dl-0.8.1.tar.gz",
"platform": null,
"description": "# Pinterest Media Downloader (pinterest-dl)\n[](https://pypi.org/project/pinterest-dl/)\n[](https://pypi.org/project/pinterest-dl/)\n[](https://github.com/sean1832/pinterest-dl/blob/main/LICENSE)\n[](https://pepy.tech/project/pinterest-dl)\n\n<a href=\"https://www.buymeacoffee.com/zekezhang\" target=\"_blank\"><img src=\"https://cdn.buymeacoffee.com/buttons/v2/default-blue.png\" alt=\"Buy Me A Coffee\" style=\"height: 40px !important;width: 145px !important;\" ></a>\n\n\n**English | [\u4e2d\u6587](README_CN.md)**\n\n\nThis library facilitates the scraping and downloading of medias (including images and video stream) from [Pinterest](https://pinterest.com). Using reverse engineered Pinterest API and [Selenium](https://selenium.dev) for automation, it enables users to extract images from a specified Pinterest URL and save them to a chosen directory.\n\nIt includes a [CLI](#-cli-usage) for direct usage and a [Python API](#\ufe0f-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.\n\n> [!TIP]\n> If you are looking for a GUI version of this tool, check out [pinterest-dl-gui](https://github.com/sean1832/pinterest-dl-gui).\n> 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.\n\n> [!WARNING] \n> 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](https://developers.pinterest.com/terms/). The repository owner disclaims any liability for misuse of this tool. Use it responsibly and at your own legal risk.\n\n> [!NOTE]\n> This project draws inspiration from [pinterest-image-scraper](https://github.com/xjdeng/pinterest-image-scraper).\n\n\n# Table of Contents\n- [Pinterest Media Downloader (pinterest-dl)](#pinterest-media-downloader-pinterest-dl)\n- [Table of Contents](#table-of-contents)\n - [\ud83c\udf1f Features](#-features)\n - [\ud83d\udea9 Known Issues](#-known-issues)\n - [\ud83d\udccb Requirements](#-requirements)\n - [\ud83d\udce5 Installation](#-installation)\n - [Using pip (Recommended)](#using-pip-recommended)\n - [Cloning from GitHub](#cloning-from-github)\n - [\ud83d\ude80 CLI-Usage](#-cli-usage)\n - [General Command Structure](#general-command-structure)\n - [Commands](#commands)\n - [1. Login](#1-login)\n - [2. Scrape](#2-scrape)\n - [3. Search](#3-search)\n - [4. Download](#4-download)\n - [\ud83d\udee0\ufe0f Python API](#\ufe0f-python-api)\n - [1. High-level Scrape and Download](#1-high-level-scrape-and-download)\n - [1a. Scrape with Cookies for Private Boards](#1a-scrape-with-cookies-for-private-boards)\n - [2. Detailed Scraping with Lower-Level Control](#2-detailed-scraping-with-lower-level-control)\n - [2a. With API](#2a-with-api)\n - [Scrape Media](#scrape-media)\n - [Search Media](#search-media)\n - [2b. With Browser](#2b-with-browser)\n - [\ud83e\udd1d Contributing](#-contributing)\n - [\ud83d\udcdc License](#-license)\n\n## \ud83c\udf1f Features\n- \u2705 Scrape media directly from a Pinterest URL.\n- \u2705 Asynchronously download media from a list of URLs. ([#1](https://github.com/sean1832/pinterest-dl/pull/1))\n- \u2705 Save scraped URLs to a JSON file for future access.\n- \u2705 Incognito mode to keep your scraping discrete.\n- \u2705 Access detailed output for effective debugging.\n- \u2705 Support for the Firefox browser.\n- \u2705 Insert `alt` text for media as metadata `comment` in the downloaded media for searchability.\n- \u2705 Optionally save `alt` text as a separate text file for each media. ([#32](https://github.com/sean1832/pinterest-dl/pull/32))\n- \u2705 Scrape private boards and pins with browser cookies. ([#20](https://github.com/sean1832/pinterest-dl/pull/20))\n- \u2705 Scrape media using reversed engineered Pinterest API. (This will be default behaviour. You can use webdriver by specifying `--client chrome` or `--client firefox`) ([#21](https://github.com/sean1832/pinterest-dl/pull/21))\n- \u2705 Search for media on Pinterest using a query. ([#23](https://github.com/sean1832/pinterest-dl/pull/23))\n- \u2705 Support multiple urls and queries in a single command.\n- \u2705 Support for batch processing of URLs and queries from files.\n- \u2705 Download video streams if available.\n\n## \ud83d\udea9 Known Issues\n- \ud83d\udd32 Not yet implement testing.\n- \ud83d\udd32 Not sorely tested on ~~Linux and~~ Mac. Please create an [Issue](https://github.com/sean1832/pinterest-dl/issues) to report any bugs.\n\n## \ud83d\udccb Requirements\n- Python 3.10 or newer\n- (Optional) Chrome or Firefox browser\n- [ffmpeg](https://ffmpeg.org/) added to your PATH for video stream downloading (with `--video` option)\n\n## \ud83d\udce5 Installation\n\n### Using pip (Recommended)\n```bash\npip install pinterest-dl\n```\n\n### Cloning from GitHub\n```bash\ngit clone https://github.com/sean1832/pinterest-dl.git\ncd pinterest-dl\npip install .\n```\n\n## \ud83d\ude80 CLI-Usage\n\n### General Command Structure\n```bash\npinterest-dl [command] [options]\n```\n\n| Command | Description |\n| ------------------------- | ---------------------------------------------------------------------------------- |\n| [`login`](#1-login) | Login to Pinterest to obtain browser cookies for scraping private boards and pins. |\n| [`scrape`](#2-scrape) | Scrape images from a Pinterest URL. |\n| [`search`](#3-search) | Search for images on Pinterest using a query. |\n| [`download`](#4-download) | Download images from a list of URLs provided in a JSON file. |\n\n\n---\n\n### Commands\n\n#### 1. Login \nAuthenticate to Pinterest and save browser cookies for private boards/pins.\n\n```bash\npinterest-dl login [options]\n```\n\n\n\n| Options | Description | Default |\n| --------------------------- | ------------------------- | -------------- |\n| `-o`, `--output [file]` | Path to save cookies file | `cookies.json` |\n| `--client [chrome/firefox]` | Browser client to use | `chrome` |\n| `--headful` | Show browser window | - |\n| `--incognito` | Use incognito mode | - |\n| `--verbose` | Enable debug output | - |\n\n> [!TIP]\n> After running `login`, you\u2019ll be prompted for your Pinterest email/password. Cookies are then saved to the specified file.\n\n\n---\n\n#### 2. Scrape \nDownload images from a Pin, Board URL, or a list of URLs.\n\n```bash\n# Single or multiple URLs:\npinterest-dl scrape <url1> <url2> \u2026\n\n# From one or more files (one URL per line):\npinterest-dl scrape -f urls.txt [options]\npinterest-dl scrape -f urls1.txt -f urls2.txt [options]\n\n# From stdin:\ncat urls.txt | pinterest-dl scrape -f - [options]\n```\n\n\n| Options | Description | Default |\n| ------------------------------------ | -------------------------------------------------------- | -------------- |\n| `-f`, `--file [file]` | Path to file with URLs (one per line); use `-` for stdin | \u2013 |\n| `<url>` | One or more Pinterest URLs | \u2013 |\n| `-o`, `--output [directory]` | Directory to save images (stdout if omitted) | \u2013 |\n| `-c`, `--cookies [file]` | Path to cookies file (for private content) | `cookies.json` |\n| `-n`, `--num [number]` | Maximum images to download | `100` |\n| `-r`, `--resolution [WxH]` | Minimum image resolution (e.g. `512x512`) | \u2013 |\n| `--video` | Download video stream (if available) | \u2013 |\n| `--timeout [seconds]` | Request timeout | `3` |\n| `--delay [seconds]` | Delay between requests | `0.2` |\n| `--cache [path]` | Save scraped URLs to JSON | \u2013 |\n| `--caption [txt/json/metadata/none]` | Caption format: `txt`, `json`, `metadata`, or `none` | `none` |\n| `--ensure-cap` | Require alt text on every image | \u2013 |\n| `--client [api/chrome/firefox]` | Scraper backend | `api` |\n| `--headful` | Show browser window (chrome/firefox only) | \u2013 |\n| `--incognito` | Use incognito mode (chrome/firefox only) | \u2013 |\n| `--verbose` | Enable debug output | \u2013 |\n\n---\n\n#### 3. Search \nFind and download images via a search query (API mode only), or from URL-lists in files.\n\n```bash\n# Simple query:\npinterest-dl search <query1> <query2> ... [options]\n\n# From one or more files:\npinterest-dl search -f queries.txt [options]\npinterest-dl search -f q1.txt -f q2.txt [options]\n\n# From stdin:\ncat queries.txt | pinterest-dl search -f - [options]\n```\n\n\n\n| Options | Description | Default |\n| ------------------------------------ | ----------------------------------------------------------- | -------------- |\n| `-f`, `--file [file]` | Path to file with queries (one per line); use `-` for stdin | \u2013 |\n| `<query>` | One or more search terms | \u2013 |\n| `-o`, `--output [directory]` | Directory to save images (stdout if omitted) | \u2013 |\n| `-c`, `--cookies [file]` | Path to cookies file | `cookies.json` |\n| `-n`, `--num [number]` | Maximum images to download | `100` |\n| `-r`, `--resolution [WxH]` | Minimum image resolution | \u2013 |\n| `--video` | Download video stream (if available) | \u2013 |\n| `--timeout [seconds]` | Request timeout | `3` |\n| `--delay [seconds]` | Delay between requests | `0.2` |\n| `--cache [path]` | Save results to JSON | \u2013 |\n| `--caption [txt/json/metadata/none]` | Caption format | `none` |\n| `--ensure-cap` | Require alt text on every image | \u2013 |\n| `--verbose` | Enable debug output | \u2013 |\n\n---\n\n#### 4. Download \nFetch images from a previously saved cache file.\n\n```bash\npinterest-dl download <cache.json> [options]\n```\n\n\n| Options | Description | Default |\n| -------------------------- | ------------------------ | ------------------- |\n| `-o`, `--output [dir]` | Directory to save images | `./<json_filename>` |\n| `-r`, `--resolution [WxH]` | Minimum image resolution | - |\n| `--verbose` | Enable debug output | - |\n\n\n## \ud83d\udee0\ufe0f Python API\nYou can also use the `PinterestDL` class directly in your Python code to scrape and download images programmatically.\n\n### 1. High-level Scrape and Download\nThis example shows how to **scrape** and download images from a Pinterest URL in one step.\n\n```python\nfrom pinterest_dl import PinterestDL\n\n# Initialize and run the Pinterest image downloader with specified settings\nimages = PinterestDL.with_api(\n timeout=3, # Timeout in seconds for each request (default: 3)\n verbose=False, # Enable detailed logging for debugging (default: False)\n ensure_alt=True, # Ensure every image has alt text (default: False)\n).scrape_and_download(\n url=\"https://www.pinterest.com/pin/1234567\", # Pinterest URL to scrape\n output_dir=\"images/art\", # Directory to save downloaded images\n num=30, # Max number of images to download \n download_streams=True, # Download video streams if available (default: False)\n min_resolution=(512, 512), # Minimum resolution for images (width, height) (default: None)\n cache_path=\"art.json\", # Path to cache scraped data as json (default: None)\n caption=\"txt\", # Caption format for downloaded images: 'txt' for alt text in separate files, 'json' for full image data in seperate file, 'metadata' embeds in image files, 'none' for no captions\n delay=0.4, # Delay between requests (default: 0.2)\n)\n```\n\nThis example shows how to **search** with query and download images from a Pinterest URL in one step.\n\n```python\nfrom pinterest_dl import PinterestDL\n\n# Initialize and run the Pinterest image downloader with specified settings\n# `search_and_download` is only available in API mode\nimages = PinterestDL.with_api( \n timeout=3, # Timeout in seconds for each request (default: 3)\n verbose=False, # Enable detailed logging for debugging (default: False)\n ensure_alt=True, # Ensure every image has alt text (default: False)\n).search_and_download(\n query=\"art\", # Pinterest search query\n output_dir=\"images/art\", # Directory to save downloaded images\n num=30, # Max number of images to download \n download_streams=True, # Download video stream if available (default: False)\n min_resolution=(512, 512), # Minimum resolution for images (width, height) (default: None)\n cache_path=\"art.json\", # Path to cache scraped data as json (default: None)\n caption=\"txt\", # Caption format for downloaded images: 'txt' for alt text in separate files, 'json' for full image data in seperate file, 'metadata' embeds in image files, 'none' for no captions\n delay=0.4, # Delay between requests (default: 0.2)\n)\n```\n\n#### 1a. Scrape with Cookies for Private Boards\n**2a. Obtain cookies**\nYou need to first log in to Pinterest to obtain browser cookies for scraping private boards and pins.\n```python\nimport os\nimport json\n\nfrom pinterest_dl import PinterestDL\n\n# Make sure you don't expose your password in the code.\nemail = input(\"Enter Pinterest email: \")\npassword = os.getenv(\"PINTEREST_PASSWORD\")\n\n# Initialize browser and login to Pinterest\ncookies = PinterestDL.with_browser(\n browser_type=\"chrome\",\n headless=True,\n).login(email, password).get_cookies(\n after_sec=7, # Time to wait before capturing cookies. Login may take time.\n)\n\n# Save cookies to a file\nwith open(\"cookies.json\", \"w\") as f:\n json.dump(cookies, f, indent=4)\n```\n\n**2b. Scrape with cookies**\nAfter obtaining cookies, you can use them to scrape private boards and pins.\n```python\nimport json\nfrom pinterest_dl import PinterestDL\n\n# Load cookies from a file\nwith open(\"cookies.json\", \"r\") as f:\n cookies = json.load(f)\n\n# Initialize and run the Pinterest image downloader with specified settings\nimages = (\n PinterestDL.with_api()\n .with_cookies(\n cookies, # cookies in selenium format\n )\n .scrape_and_download(\n url=\"https://www.pinterest.com/pin/1234567\", # Assume this is a private board URL\n output_dir=\"images/art\", # Directory to save downloaded images\n num=30, # Max number of images to download\n )\n)\n```\n\n### 2. Detailed Scraping with Lower-Level Control\n\nUse this example if you need more granular control over scraping and downloading images.\n\n#### 2a. With API\n\n##### Scrape Media\n```python\nimport json\n\nfrom pinterest_dl import PinterestDL\n\n# 1. Initialize PinterestDL with API and scrape media\nscraped_medias = PinterestDL.with_api().scrape(\n url=\"https://www.pinterest.com/pin/1234567\", # URL of the Pinterest page\n num=30, # Maximum number of images to scrape\n min_resolution=(512, 512), # <- Only available to set in the API. Browser mode will have to pruned after download.\n)\n\n# 2. Download Media\n# Download media to a specified directory\noutput_dir = \"images/art\"\ndownloaded_items = PinterestDL.download_media(\n media=scraped_medias, \n output_dir=output_dir, \n download_streams=True # Download video streams if available; otherwise download images only.\n)\n\n\n# 3. Save Scraped Data to JSON (Optional)\n# Convert scraped data into a dictionary and save it to a JSON file for future access\nmedia_data = [media.to_dict() for media in scraped_medias]\nwith open(\"art.json\", \"w\") as f:\n json.dump(media_data, f, indent=4)\n\n# 4. Add Alt Text as Metadata (Optional)\n# Extract `alt` text from media and set it as metadata in the downloaded files\nPinterestDL.add_captions_to_meta(images=downloaded_items)\n\n# 4. Add Alt Text as text file (Optional)\n# Extract `alt` text from media and save it as a text file in the downloaded directory\nPinterestDL.add_captions_to_file(downloaded_items, output_dir, extension=\"txt\")\n```\n\n##### Search Media\n```python\nimport json\nfrom pinterest_dl import PinterestDL\n\n# 1. Initialize PinterestDL with API.\nscraped_medias = PinterestDL.with_api().search(\n query=\"art\", # Search query for Pinterest\n num=30, # Maximum number of images to scrape\n min_resolution=(512, 512), # Minimum resolution for images\n delay=0.4, # Delay between requests (default: 0.2)\n)\n# ... (Same as above)\n```\n\n#### 2b. With Browser\n```python\nimport json\n\nfrom pinterest_dl import PinterestDL\n\n# 1. Initialize PinterestDL with API.\nscraped_medias = PinterestDL.with_browser(\n browser_type=\"chrome\", # Browser type to use ('chrome' or 'firefox')\n headless=True, # Run browser in headless mode\n ensure_alt=True, # Ensure every image has alt text (default: False)\n).scrape(\n url=\"https://www.pinterest.com/pin/1234567\", # URL of the Pinterest page\n num=30, # Maximum number of images to scrape\n)\n\n# 2. Save Scraped Data to JSON\n# Convert scraped data into a dictionary and save it to a JSON file for future access\nmedia_data = [media.to_dict() for media in scraped_medias]\nwith open(\"art.json\", \"w\") as f:\n json.dump(media_data, f, indent=4)\n\n# 3. Download Media\n# Download media to a specified directory\noutput_dir = \"images/art\"\ndownloaded_media = PinterestDL.download_media(\n media=scraped_medias,\n output_dir=output_dir,\n download_streams=False, # <- browser mode does not support video streams yet\n)\n\n# 4. Prune Media by Resolution (Optional)\n# Remove media that do not meet the minimum resolution criteria\nkept_media = PinterestDL.prune_images(images=downloaded_media, min_resolution=(200, 200))\n\n# 5. Add Alt Text as Metadata (Optional)\n# Extract `alt` text from media and set it as metadata in the downloaded files\nPinterestDL.add_captions_to_meta(images=kept_media)\n\n# 6. Add Alt Text as text file (Optional)\n# Extract `alt` text from media and save it as a text file in the downloaded directory\nPinterestDL.add_captions_to_file(kept_media, output_dir, extension=\"txt\")\n```\n\n## \ud83e\udd1d Contributing\nContributions are welcome! Please check the [Contribution Guidelines](CONTRIBUTING.md) before submitting a pull request.\n\n## \ud83d\udcdc License\n[Apache License 2.0](LICENSE)\n",
"bugtrack_url": null,
"license": "Apache-2.0",
"summary": "An unofficial Pinterest image downloader",
"version": "0.8.1",
"project_urls": {
"Homepage": "https://github.com/sean1832/pinterest-dl",
"Issues": "https://github.com/sean1832/pinterest-dl/issues"
},
"split_keywords": [
"pinterest",
" image downloader",
" web scraping"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "c5da6e6a000f5f7bcd6cbf3503319c8e74500c250f9ea53400af3a6277313938",
"md5": "d59ee90633dc8d1f8e4114c4459ae137",
"sha256": "f90a21625205a74587f8d0733a0b8f61d2ff09c84bcbbcfb8f2510ab234dbcdc"
},
"downloads": -1,
"filename": "pinterest_dl-0.8.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "d59ee90633dc8d1f8e4114c4459ae137",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 51555,
"upload_time": "2025-08-11T14:17:31",
"upload_time_iso_8601": "2025-08-11T14:17:31.337039Z",
"url": "https://files.pythonhosted.org/packages/c5/da/6e6a000f5f7bcd6cbf3503319c8e74500c250f9ea53400af3a6277313938/pinterest_dl-0.8.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "ad627ae7d13260c76737c210c000f31b21ec2db6dbf13deb2658ee4b3474397e",
"md5": "110feecaf89c89a9766adadc837b7663",
"sha256": "531dffa6796e469dd9da6d332bd5c9702d96a7c6179cbe93468483bbe72f179a"
},
"downloads": -1,
"filename": "pinterest_dl-0.8.1.tar.gz",
"has_sig": false,
"md5_digest": "110feecaf89c89a9766adadc837b7663",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 393989,
"upload_time": "2025-08-11T14:17:32",
"upload_time_iso_8601": "2025-08-11T14:17:32.666490Z",
"url": "https://files.pythonhosted.org/packages/ad/62/7ae7d13260c76737c210c000f31b21ec2db6dbf13deb2658ee4b3474397e/pinterest_dl-0.8.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-11 14:17:32",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "sean1832",
"github_project": "pinterest-dl",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "pinterest-dl"
}
JSON
