Skip to main content

sharepoint-dl

sharepoint-dl logo

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

CI Coverage PyPI Python License: MIT


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

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.

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 chromium once.

Prefer not to let sp-dl open a browser? Export cookies yourself:

  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

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:

  1. Reads the video's player metadata from the stream page (needs your SharePoint session)
  2. Extracts the pre-signed media-proxy token SharePoint embeds for its own player
  3. Builds a DASH manifest URL from it — no OAuth token or cookies are needed for the media proxy
  4. Downloads all video/audio segments in parallel (10 concurrent connections)
  5. 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) or apt 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-dl launches 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's FedAuth cookie to appear. Captured cookies are stored with 0600 permissions in ~/.config/sp-dl/browser-cookies/<domain>.json and validated before each run; when they expire, the saved profile usually lets sp-dl refresh them silently in the background. Use sp-dl auth logout to 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

MIT

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)

Source distribution for sharepoint-dl 1.2.0
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)

Table of built distributions (wheels) for sharepoint-dl 1.2.0
File Interpreter ABI Platform Actions
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

Release files / sharepoint_dl-1.2.0.tar.gz

Download URL sharepoint_dl-1.2.0.tar.gz
Size 76.9 kB
Tags Source
SHA-256 checksum
How to use checksums
c1f14322b72e2589fa1bc63b3578e1583a66045e5b7bbc4b213b530a45117123
BLAKE2b-256 checksum
How to use checksums
1288abcafb15254138fa151d3f5cf8e6ba18083274e381242e0b4f57aa895832
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

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 Oct 21, 2026.

Transparency log

Release files / sharepoint_dl-1.2.0-py3-none-any.whl

Download URL sharepoint_dl-1.2.0-py3-none-any.whl
Size 65.1 kB
Tags Python 3
SHA-256 checksum
How to use checksums
e40a79037f9b3ca9a243e328d8288ac20c131dfe2e147af9cad4ff47904076a1
BLAKE2b-256 checksum
How to use checksums
4f9d05dd477cc63c8ad1b1e99a06e35a4df5f0acfa59c40b2c8a1400ddade42a
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

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 Oct 21, 2026.

Transparency log

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.

Select from 2 files

Attestation for sharepoint_dl-1.2.0.tar.gz

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 Oct 21, 2026.

Transparency log

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.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page