sharepoint-dl

Download videos and files from SharePoint — like yt-dlp for SharePoint.

Why?

• Microsoft Stream (Classic) was retired — all videos now live in SharePoint / OneDrive
• Browser downloads fail for large files, offer no resume, and require clicking through menus
• Enterprise tenants often block direct downloads — sp-dl handles this automatically via adaptive streaming
• yt-dlp doesn't support SharePoint authentication
• sp-dl gives you one command to download any file from SharePoint

What It Downloads

Install

pip install sharepoint-dl

Or with pipx for isolated install:

pipx install sharepoint-dl

Quick Start

First time? Run sp-dl quickstart for a step-by-step guide.

Using Cookies (Recommended — Easiest)

1. Log into SharePoint in your browser
2. Export cookies to a file using a browser extension like "Get cookies.txt LOCALLY"
3. Download:

sp-dl download "https://contoso.sharepoint.com/sites/Team/_layouts/15/stream.aspx?id=/sites/Team/Shared%20Documents/demo.mp4" \
  --cookies cookies.txt

Using Device Code (OAuth — for enterprise tenants)

# One-time login (you'll be prompted for your org tenant)
sp-dl auth login --tenant contoso

# Download (uses saved token)
sp-dl download "https://contoso.sharepoint.com/sites/Team/Shared%20Documents/video.mp4"

Download-Blocked Videos (Enterprise Tenants)

Some organizations disable direct file downloads via SharePoint admin policy. sp-dl detects this automatically and switches to parallel adaptive streaming:

# Works even when admin has blocked downloads!
# sp-dl detects the block → prompts OAuth2 login → streams via DASH manifest
sp-dl download "https://contoso-my.sharepoint.com/personal/user/_layouts/15/stream.aspx?id=..." \
  --cookies cookies.txt

How it works:

1. Detects download-blocked policy from the stream page or 401/403 response
2. Acquires an OAuth2 token via device code flow (cached per-domain for future use)
3. Builds a DASH manifest URL via Microsoft's media proxy
4. Downloads all video/audio segments in parallel (10 concurrent connections)
5. Muxes audio + video into a single MP4 using ffmpeg

Requires ffmpeg for final muxing: brew install ffmpeg (macOS) or apt install ffmpeg (Linux)

Usage

# Download a video
sp-dl download <URL> --cookies cookies.txt

# Download from a sharing link
sp-dl download "https://contoso.sharepoint.com/:v:/s/Team/EaBcDeFgHiJk" -c cookies.txt

# Show file info without downloading
sp-dl download <URL> --info -c cookies.txt

# JSON metadata
sp-dl download <URL> --json -c cookies.txt

# Custom output path
sp-dl download <URL> -o ~/Videos/meeting.mp4 -c cookies.txt

# Output template
sp-dl download <URL> -o "%(site)s/%(folder)s/%(filename)s" -c cookies.txt

# Limit speed
sp-dl download <URL> --limit-rate 5M -c cookies.txt

# Skip existing files
sp-dl download <URL> --no-overwrites -c cookies.txt

# Batch download (one URL per line)
sp-dl batch urls.txt -c cookies.txt

# Quick start guide
sp-dl quickstart

Supported URL Patterns

Authentication Methods

Enterprise users: When direct downloads are blocked by admin policy, sp-dl automatically falls back to OAuth2 + adaptive streaming. Your first download will prompt for a device code login, and the token is cached for subsequent downloads.

Auth Management

sp-dl auth login --tenant contoso       # Device code login (prompted for tenant)
sp-dl auth login --tenant contoso -i    # Browser-based login
sp-dl auth status                        # Check auth state
sp-dl auth logout                        # Clear tokens

Tip: You can pass a SharePoint URL as the tenant and it will be auto-detected: sp-dl auth login --tenant https://contoso.sharepoint.com

Output Templates

Configuration

Create ~/.config/sp-dl/config.toml:

[defaults]
output_template = "%(filename)s"
cookies_file = "/path/to/cookies.txt"
retries = 5
no_overwrites = false

[auth]
tenant = "contoso.onmicrosoft.com"

Environment variables: SP_DL_COOKIES, SP_DL_TENANT, SP_DL_CLIENT_ID, SP_DL_OUTPUT

Development

git clone https://github.com/bhayanak/sp-dl.git
cd sp-dl
pip install -e ".[dev]"

# Run tests with coverage
pytest --cov=sp_dl -v

# Lint & format
ruff check src/ tests/
ruff format src/ tests/

License

MIT