{"id":38663953,"url":"https://github.com/sean1832/pinterest-dl","last_synced_at":"2026-01-17T09:44:16.385Z","repository":{"id":230574414,"uuid":"779680413","full_name":"sean1832/pinterest-dl","owner":"sean1832","description":"An unofficial Pinterest media downloader","archived":false,"fork":false,"pushed_at":"2025-08-11T15:55:56.000Z","size":771,"stargazers_count":77,"open_issues_count":2,"forks_count":12,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-11-16T10:20:14.623Z","etag":null,"topics":["automation","cli","m3u8","pinterest","pinterest-api","pinterest-downloader","scraper","selenium"],"latest_commit_sha":null,"homepage":"https://pypi.org/project/pinterest-dl","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/sean1832.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2024-03-30T14:00:23.000Z","updated_at":"2025-11-11T23:11:58.000Z","dependencies_parsed_at":"2024-11-22T06:24:23.731Z","dependency_job_id":"77029448-6ae6-4a6a-a06c-e0b9e1ae46b7","html_url":"https://github.com/sean1832/pinterest-dl","commit_stats":null,"previous_names":["sean1832/pinterest-cli","sean1832/pinterest-dl"],"tags_count":24,"template":false,"template_full_name":null,"purl":"pkg:github/sean1832/pinterest-dl","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sean1832%2Fpinterest-dl","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sean1832%2Fpinterest-dl/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sean1832%2Fpinterest-dl/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sean1832%2Fpinterest-dl/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/sean1832","download_url":"https://codeload.github.com/sean1832/pinterest-dl/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sean1832%2Fpinterest-dl/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28505565,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-17T06:57:29.758Z","status":"ssl_error","status_checked_at":"2026-01-17T06:56:03.931Z","response_time":85,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["automation","cli","m3u8","pinterest","pinterest-api","pinterest-downloader","scraper","selenium"],"created_at":"2026-01-17T09:44:16.200Z","updated_at":"2026-01-17T09:44:16.327Z","avatar_url":"https://github.com/sean1832.png","language":"Python","funding_links":["https://www.buymeacoffee.com/zekezhang"],"categories":[],"sub_categories":[],"readme":"# Pinterest Media Downloader (pinterest-dl)\n[![PyPI - Version](https://img.shields.io/pypi/v/pinterest-dl)](https://pypi.org/project/pinterest-dl/)\n[![PyPI - Python Version](https://img.shields.io/badge/python-%3E%3D3.10-blue\n)](https://pypi.org/project/pinterest-dl/)\n[![PyPI - License](https://img.shields.io/pypi/l/pinterest-dl)](https://github.com/sean1832/pinterest-dl/blob/main/LICENSE)\n[![Downloads](https://static.pepy.tech/badge/pinterest-dl)](https://pepy.tech/project/pinterest-dl)\n\n\u003ca href=\"https://www.buymeacoffee.com/zekezhang\" target=\"_blank\"\u003e\u003cimg src=\"https://cdn.buymeacoffee.com/buttons/v2/default-blue.png\" alt=\"Buy Me A Coffee\" style=\"height: 40px !important;width: 145px !important;\" \u003e\u003c/a\u003e\n\n\n**English | [中文](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](#️-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\u003e [!TIP]\n\u003e If you are looking for a GUI version of this tool, check out [pinterest-dl-gui](https://github.com/sean1832/pinterest-dl-gui).\n\u003e 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\u003e [!WARNING] \n\u003e 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\u003e [!NOTE]\n\u003e 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  - [🌟 Features](#-features)\n  - [🚩 Known Issues](#-known-issues)\n  - [📋 Requirements](#-requirements)\n  - [📥 Installation](#-installation)\n    - [Using pip (Recommended)](#using-pip-recommended)\n    - [Cloning from GitHub](#cloning-from-github)\n  - [🚀 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  - [🛠️ Python API](#️-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  - [🤝 Contributing](#-contributing)\n  - [📜 License](#-license)\n\n## 🌟 Features\n- ✅ Scrape media directly from a Pinterest URL.\n- ✅ Asynchronously download media from a list of URLs. ([#1](https://github.com/sean1832/pinterest-dl/pull/1))\n- ✅ Save scraped URLs to a JSON file for future access.\n- ✅ Incognito mode to keep your scraping discrete.\n- ✅ Access detailed output for effective debugging.\n- ✅ Support for the Firefox browser.\n- ✅ Insert `alt` text for media as metadata `comment` in the downloaded media for searchability.\n- ✅ Optionally save `alt` text as a separate text file for each media. ([#32](https://github.com/sean1832/pinterest-dl/pull/32))\n- ✅ Scrape private boards and pins with browser cookies. ([#20](https://github.com/sean1832/pinterest-dl/pull/20))\n- ✅ 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- ✅ Search for media on Pinterest using a query. ([#23](https://github.com/sean1832/pinterest-dl/pull/23))\n- ✅ Support multiple urls and queries in a single command.\n- ✅ Support for batch processing of URLs and queries from files.\n- ✅ Download video streams if available.\n\n## 🚩 Known Issues\n- 🔲 Not able to scrape nested boards yet.\n\n## 📋 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## 📥 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## 🚀 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![login](doc/images/pinterest-dl-login.gif)\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\u003e [!TIP]\n\u003e  After running `login`, you’ll 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 \u003curl1\u003e \u003curl2\u003e …\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![scrape](doc/images/pinterest-dl-scrape.gif)\n\n| Options                              | Description                                              | Default        |\n| ------------------------------------ | -------------------------------------------------------- | -------------- |\n| `-f`, `--file [file]`                | Path to file with URLs (one per line); use `-` for stdin | –              |\n| `\u003curl\u003e`                              | One or more Pinterest URLs                               | –              |\n| `-o`, `--output [directory]`         | Directory to save images (stdout if omitted)             | –              |\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`)                | –              |\n| `--video`                            | Download video stream (if available)                     | –              |\n| `--timeout [seconds]`                | Request timeout                                          | `3`            |\n| `--delay [seconds]`                  | Delay between requests                                   | `0.2`          |\n| `--cache [path]`                     | Save scraped URLs to JSON                                | –              |\n| `--caption [txt/json/metadata/none]` | Caption format: `txt`, `json`, `metadata`, or `none`     | `none`         |\n| `--ensure-cap`                       | Require alt text on every image                          | –              |\n| `--client [api/chrome/firefox]`      | Scraper backend                                          | `api`          |\n| `--headful`                          | Show browser window (chrome/firefox only)                | –              |\n| `--incognito`                        | Use incognito mode (chrome/firefox only)                 | –              |\n| `--verbose`                          | Enable debug output                                      | –              |\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 \u003cquery1\u003e \u003cquery2\u003e ... [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![search](doc/images/pinterest-dl-search.gif)\n\n| Options                              | Description                                                 | Default        |\n| ------------------------------------ | ----------------------------------------------------------- | -------------- |\n| `-f`, `--file [file]`                | Path to file with queries (one per line); use `-` for stdin | –              |\n| `\u003cquery\u003e`                            | One or more search terms                                    | –              |\n| `-o`, `--output [directory]`         | Directory to save images (stdout if omitted)                | –              |\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                                    | –              |\n| `--video`                            | Download video stream (if available)                        | –              |\n| `--timeout [seconds]`                | Request timeout                                             | `3`            |\n| `--delay [seconds]`                  | Delay between requests                                      | `0.2`          |\n| `--cache [path]`                     | Save results to JSON                                        | –              |\n| `--caption [txt/json/metadata/none]` | Caption format                                              | `none`         |\n| `--ensure-cap`                       | Require alt text on every image                             | –              |\n| `--verbose`                          | Enable debug output                                         | –              |\n\n---\n\n#### 4. Download  \nFetch images from a previously saved cache file.\n\n```bash\npinterest-dl download \u003ccache.json\u003e [options]\n```\n![download](doc/images/pinterest-dl-download.gif)\n\n| Options                    | Description              | Default             |\n| -------------------------- | ------------------------ | ------------------- |\n| `-o`, `--output [dir]`     | Directory to save images | `./\u003cjson_filename\u003e` |\n| `-r`, `--resolution [WxH]` | Minimum image resolution | -                   |\n| `--verbose`                | Enable debug output      | -                   |\n\n\n## 🛠️ 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),  # \u003c- 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,  # \u003c- 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## 🤝 Contributing\nContributions are welcome! Please check the [Contribution Guidelines](CONTRIBUTING.md) before submitting a pull request.\n\n## 📜 License\n[Apache License 2.0](LICENSE)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsean1832%2Fpinterest-dl","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsean1832%2Fpinterest-dl","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsean1832%2Fpinterest-dl/lists"}