Pinterest Media Downloader (pinterest-dl)
English | 中文
CLI to download images and videos from any Pinterest board, pin, or search query.
Features
- Scrape and download images and videos from any board, pin, section, or search query.
- API-first and fast: scrapes through Pinterest's API by default, with optional Playwright browser automation.
- Download videos as MP4 (with ffmpeg) or as raw .ts streams (no ffmpeg required).
- Reach private boards and pins by authenticating with browser cookies.
- Scrape multiple URLs or queries at once, or batch them from a file.
- Download asynchronously, and save scraped URLs to JSON to re-download later.
- Embed alt text as an EXIF comment for searchability, or save it as a sidecar text file.
Installation
Requires Python 3.10 or newer.
pip install pinterest-dl
Optional extras add image and metadata features:
| Command | Adds |
|---|---|
pip install pinterest-dl[browser] |
Browser automation for --client chromium/firefox and login (Playwright) |
pip install pinterest-dl[image] |
Image resolution detection and pruning (Pillow) |
pip install pinterest-dl[metadata] |
Embed alt text as EXIF metadata (adds pyexiv2; includes [image]) |
Some features need extra tools on your system:
- Browser backends: install the extra with
pip install pinterest-dl[browser], then runplaywright install chromium(orfirefox) before using--client chromium/firefox. The API client (default) needs neither. To capture cookies from an already-installed browser without Playwright, usepinterest-dl login --from-browser. - Video to MP4: install ffmpeg. Without it, use
--skip-remuxto keep the raw .ts file.
See Optional Dependencies for the full matrix.
Install from source
git clone https://github.com/sean1832/pinterest-dl.git
cd pinterest-dl
pip install . # or: pip install .[all]
Quick Start
Command line
# Download a single pin (pin URLs return the pin itself)
pinterest-dl scrape "<pin_url>" -o ./output
# Download a pin plus related pins (pin + 49 related)
pinterest-dl scrape "<pin_url>" -o ./output -n 50
# Search and download 30 pins
pinterest-dl search "nature photography" -o ./output -n 30
# Download a pin's video as MP4 (needs ffmpeg)
pinterest-dl scrape "<pin_url>" --video -o ./output
# Reach a private board: log in once, then pass the cookies
# No extra install needed - reads cookies from your Firefox browser:
pinterest-dl login --from-browser -o cookies.json
# Or use Playwright (requires: pip install pinterest-dl[browser] && playwright install chromium):
# pinterest-dl login -o cookies.json
pinterest-dl scrape "<private_board_url>" -c cookies.json -o ./output
# Machine-readable output: emit JSON to stdout (no -o means metadata only)
pinterest-dl scrape "<pin_url>" -n 10 --json | jq '.results[0].items[].src'
Read the full CLI guide for every command and option.
Python
from pinterest_dl import PinterestDL
# Scrape a board and download the images
images = PinterestDL.with_api().scrape_and_download(
url="https://www.pinterest.com/username/board-name/",
output_dir="images/art",
num=30,
)
# Search and download
images = PinterestDL.with_api().search_and_download(
query="landscape art",
output_dir="images/landscapes",
num=50,
)
Read the full API guide or browse runnable examples.
Documentation
- CLI guide - every command and option
- Python API guide - programmatic usage and patterns
- Optional dependencies - the full extras matrix
- Testing guide - offline-by-default tests and live integration tests
- Contributing - how to contribute
Disclaimer
Related
- pinterest-dl-gui - a graphical interface built on this library.
- Inspired by pinterest-image-scraper.
Contributing
Contributions are welcome. See CONTRIBUTING.md for the code of conduct, commit conventions, and pull request process.
License
Licensed under the Apache 2.0 License. See LICENSE.
Support
If this tool saved you time, you can buy me a coffee.
Made by sean1832. Not affiliated with Pinterest; all trademarks are property of their respective owners.
1 maintainer
Metadata
1 maintainer
Release files for pinterest-dl 1.3.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| pinterest_dl-1.3.0.tar.gz | 72.3 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| pinterest_dl-1.3.0-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 142.1 kB
Release files / pinterest_dl-1.3.0.tar.gz
| Download URL | pinterest_dl-1.3.0.tar.gz |
|---|---|
| Size | 72.3 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
55be53434eb81f5ad4518656ff9ec6867c61a5f7161d153fef7e8735bc40aac8
|
|
BLAKE2b-256 checksum How to use checksums |
dd61ad7bcbbc2c8f79e0d55ab06c10f980d61cb1f861c55a2e7c6496a460989b
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.12
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Jun 15, 2026.
Transparency logRelease files / pinterest_dl-1.3.0-py3-none-any.whl
| Download URL | pinterest_dl-1.3.0-py3-none-any.whl |
|---|---|
| Size | 69.8 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
6648112f16378ea7eb4edb4b3342c5524b8beec7bc0ac9d0022fa156eb744f12
|
|
BLAKE2b-256 checksum How to use checksums |
6f8e3065e0041dce5f432ffc5d53960a0ca686928ec9e7c55a2a3758edda66d8
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.12
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Jun 15, 2026.
Transparency log
