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-dlhandles this automatically via adaptive streaming - yt-dlp doesn't support SharePoint authentication
sp-dlgives you one command to download any file from SharePoint
What It Downloads
| Content | Source |
|---|---|
| Videos (.mp4, .mov, .webm) | SharePoint document libraries, Stream on SharePoint |
| Meeting recordings | OneDrive / SharePoint auto-saved recordings |
| Download-blocked videos | Enterprise tenants with admin download restrictions |
| Any file | SharePoint document libraries |
| Shared links | Anonymous or org-internal sharing links |
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.
Just paste the URL (Recommended)
sp-dl download "https://contoso-my.sharepoint.com/personal/user/_layouts/15/stream.aspx?id=..."
That's it. On first run a browser window opens (your installed Chrome or Edge) — sign in to
SharePoint as usual (SSO/MFA all work). sp-dl captures the session cookies, closes the window,
and downloads. The session is saved under ~/.config/sp-dl/ and reused for later downloads, so
you normally only sign in once.
If neither Chrome nor Edge is installed, run
playwright install chromiumonce.
Using a Cookie File
Prefer not to let sp-dl open a browser? Export cookies yourself:
- Log into SharePoint in your browser
- Export cookies to a file using a browser extension like "Get cookies.txt LOCALLY"
- Download:
sp-dl download "https://contoso.sharepoint.com/sites/Team/_layouts/15/stream.aspx?id=/sites/Team/Shared%20Documents/demo.mp4" \
--cookies cookies.txt
Headless / SSH (OAuth device code)
sp-dl download "https://contoso.sharepoint.com/sites/Team/Shared%20Documents/video.mp4" --device-code
Download-Blocked Videos (Enterprise Tenants)
Some organizations disable direct file downloads via SharePoint admin policy. sp-dl handles this
automatically — no extra login or flags:
sp-dl download "https://contoso-my.sharepoint.com/personal/user/_layouts/15/stream.aspx?id=..."
How it works:
- Reads the video's player metadata from the stream page (needs your SharePoint session)
- Extracts the pre-signed media-proxy token SharePoint embeds for its own player
- Builds a DASH manifest URL from it — no OAuth token or cookies are needed for the media proxy
- Downloads all video/audio segments in parallel (10 concurrent connections)
- Muxes audio + video into a single MP4 using ffmpeg
For non-blocked videos the same metadata contains a pre-signed direct download URL, which is used as-is for maximum speed.
Requires ffmpeg for final muxing of blocked videos:
brew install ffmpeg(macOS) orapt install ffmpeg(Linux)
Usage
# Download a video (browser sign-in on first run, then reused)
sp-dl download <URL>
# Download from a sharing link
sp-dl download "https://contoso.sharepoint.com/:v:/s/Team/EaBcDeFgHiJk"
# Show file info without downloading
sp-dl download <URL> --info
# JSON metadata
sp-dl download <URL> --json
# Custom output path
sp-dl download <URL> -o ~/Videos/meeting.mp4
# Output template
sp-dl download <URL> -o "%(site)s/%(folder)s/%(filename)s"
# Limit speed
sp-dl download <URL> --limit-rate 5M
# Skip existing files
sp-dl download <URL> --no-overwrites
# Batch download (one URL per line)
sp-dl batch urls.txt
# Use an exported cookie file instead of browser sign-in
sp-dl download <URL> -c cookies.txt
# Quick start guide
sp-dl quickstart
Supported URL Patterns
| Pattern | Example |
|---|---|
| Stream player | https://tenant.sharepoint.com/sites/Team/_layouts/15/stream.aspx?id=... |
| Sharing link | https://tenant.sharepoint.com/:v:/s/Team/EncodedToken |
| Direct path | https://tenant.sharepoint.com/sites/Team/Shared%20Documents/file.mp4 |
| OneDrive | https://tenant-my.sharepoint.com/personal/user/Documents/file.mp4 |
| Doc.aspx | https://tenant.sharepoint.com/sites/Team/_layouts/15/Doc.aspx?sourcedoc={guid} |
Authentication Methods
| Method | Best For | Setup |
|---|---|---|
| (default) browser sign-in | Everyone with a desktop | None — sign in once in the window that opens |
--cookies |
Scripted use, or if you'd rather not let sp-dl open a browser | Export cookies (e.g. "Get cookies.txt LOCALLY" extension) |
--device-code |
Headless servers, SSH sessions | Follow the one-time device code prompt |
--client-id --client-secret |
Service accounts, CI/CD | Azure AD admin setup |
How browser sign-in works:
sp-dllaunches your installed Chrome/Edge (or Playwright's Chromium) with a dedicated profile under~/.config/sp-dl/browser-profile, opens the URL you gave it, and waits for SharePoint'sFedAuthcookie to appear. Captured cookies are stored with0600permissions in~/.config/sp-dl/browser-cookies/<domain>.jsonand validated before each run; when they expire, the saved profile usually letssp-dlrefresh them silently in the background. Usesp-dl auth logoutto wipe everything.
Auth Management
sp-dl auth status # Show saved browser sessions / OAuth token state
sp-dl auth logout # Clear browser sessions and tokens
sp-dl auth login --tenant contoso # Optional: OAuth device code login
sp-dl auth login --tenant contoso -i # Optional: OAuth browser login
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
| Field | Description | Example |
|---|---|---|
%(filename)s |
Original filename | training.mp4 |
%(title)s |
Name without extension | training |
%(ext)s |
Extension | mp4 |
%(site)s |
SharePoint site | Team |
%(folder)s |
Parent folder | Recordings |
%(date)s |
Modified date | 20260415 |
%(author)s |
Created by | John Smith |
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
Metadata
Release files for sharepoint-dl 1.2.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 | Provenance | Actions |
|---|---|---|---|---|
| sharepoint_dl-1.2.0.tar.gz | 76.9 kB | With provenance | Details for sharepoint_dl-1.2.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| sharepoint_dl-1.2.0-py3-none-any.whl | Python 3 | none | any | Details for sharepoint_dl-1.2.0-py3-none-any.whl |
Total release size: 142.0 kB
Security for sharepoint-dl 1.2.0
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.
Full provenance
Both files in this release have been uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.