pexel-downloader

Download high-quality photos and videos from Pexels.com with a simple CLI.

Quick Start

1. Install

# Using uv (recommended)
uv tool install pexel-downloader

# Or using pip
pip install pexel-downloader

2. Set your API key

Create a free account at pexels.com to get an API key, then run:

pexel-downloader config --api-key YOUR_API_KEY

Or just run pexel-downloader config and you'll be prompted to enter it.

3. Download

# Download 10 images of nature (uses your configured defaults)
pexel-downloader download nature 10

# Download 5 videos of ocean
pexel-downloader download ocean 5 video

That's it! Files are saved to your configured download directory (default: downloads/) and the full path is shown after each download.

Installation

Prerequisites

• Python 3.10+
• Pexels account for an API key: pexels.com

Install uv

uv is a fast Python package manager.

Linux / macOS:

curl -LsSf https://astral.sh/uv/install.sh | sh

Windows (PowerShell):

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

Using pip (any platform):

pip install uv

Install pexel-downloader

As a CLI tool [recommend]:

uv tool install pexel-downloader

As a library in your project:

uv add pexel-downloader

Run without installing:

uvx pexel-downloader download nature 5 image

Configuration

Interactive setup

Run pexel-downloader config to configure all settings at once. You'll be prompted for:

• API key — your Pexels API key
• Download directory — where files are saved (default: downloads)
• Content type — image or video (default: image)
• Size — download size (default: medium)

pexel-downloader config

Set individual settings

pexel-downloader config --api-key YOUR_API_KEY
pexel-downloader config --download-dir ~/Pictures/pexels
pexel-downloader config --content-type video
pexel-downloader config --size large

The configuration is stored at:

• Linux: ~/.config/pexel-downloader/config.json
• macOS: ~/Library/Application Support/pexel-downloader/config.json
• Windows: C:\Users\<user>\AppData\Roaming\pexel-downloader\config.json

API key via environment variable

You can also use the PEXEL_API_KEY environment variable (takes priority over the config file):

Linux / macOS:

export PEXEL_API_KEY="your_api_key"

Windows (Command Prompt):

set PEXEL_API_KEY=your_api_key

Windows (PowerShell):

$env:PEXEL_API_KEY = "your_api_key"

CLI Usage

pexel-downloader download QUERY NUM [CONTENT_TYPE] [OPTIONS]

CONTENT_TYPE is optional — if omitted, uses your configured default (image by default).

Examples

# Download 10 images of "nature" (uses default content type and size)
pexel-downloader download nature 10

# Download 5 videos of "ocean" starting from page 2
pexel-downloader download ocean 5 video --start-page 2

# Specify output directory and size
pexel-downloader download cats 20 image --size large -o ./my_images

# Show help
pexel-downloader --help
pexel-downloader download --help

Options

Available sizes

Images: original, large2x, large, medium, small, portrait, landscape, tiny

Videos: large, medium, small

Python API

import os
from pexel_downloader import PexelDownloader

api_key = os.environ.get("PEXEL_API_KEY")
downloader = PexelDownloader(api_key=api_key)

# Download images
downloader.download_images(query="beaches", num_images=100, save_directory="./images")

# Download videos
downloader.download_videos(query="nature", num_videos=5, save_directory="./videos", size="medium")

# Search without downloading
results = downloader.search_images(query="sunset", per_page=10)
print(results["photos"])

Demonstration

Development

# Clone the repo
git clone https://github.com/Gabriellgpc/pexel-downloader.git
cd pexel-downloader

# Install dependencies (including dev)
uv sync --group dev

# Run tests
uv run pytest tests/ -v

# Run the CLI locally
uv run pexel-downloader --help

License

MIT License. See LICENSE for details.