Authentication

yt-dlp supports various authentication methods to access content that requires login credentials. This includes private videos, premium content, and age-restricted material.

Authentication Methods

yt-dlp supports multiple authentication approaches:

Netrc File
Cookies
Command Line
Certificates

Store credentials in a .netrc file for automatic authentication

Using Netrc Files

The .netrc file is a standard way to store credentials for automatic login.

Creating a Netrc File

# Create the file
touch ${HOME}/.netrc

# Set secure permissions (read/write for owner only)
chmod 600 ${HOME}/.netrc

Netrc File Format

Add credentials in this format:

machine <extractor> login <username> password <password>

Where <extractor> is the lowercase name of the extractor.

Example Netrc File

machine youtube login myaccount@gmail.com password my_youtube_password
machine twitch login my_twitch_account_name password my_twitch_password
machine vimeo login user@example.com password vimeo_pass123

Enabling Netrc Authentication

Activate netrc authentication with the --netrc flag:

# Use default netrc location (~/.netrc)
yt-dlp --netrc URL

# Specify custom netrc location
yt-dlp --netrc-location /path/to/custom/.netrc URL

# Specify directory containing .netrc
yt-dlp --netrc-location /path/to/directory/ URL

The default netrc location is ~/.netrc on Linux/macOS and %USERPROFILE%\_netrc or %USERPROFILE%\.netrc on Windows.

Netrc in Configuration File

Add to your yt-dlp config to always use netrc:

# ~/.config/yt-dlp/config
--netrc

# Or with custom location
--netrc-location ~/.config/yt-dlp/.netrc

Encrypted Netrc with GPG

For enhanced security, encrypt your netrc file:

Create Encrypted Netrc

# Create and edit .authinfo file
nano ~/.authinfo

# Add credentials (same format as .netrc)
machine youtube login myaccount@gmail.com password my_youtube_password

# Encrypt with GPG
gpg -c ~/.authinfo
# This creates ~/.authinfo.gpg

# Remove unencrypted file
rm ~/.authinfo

Use Encrypted Netrc

Use --netrc-cmd to decrypt on-the-fly:

yt-dlp --netrc-cmd 'gpg --decrypt ~/.authinfo.gpg' URL

Custom Netrc Command

The --netrc-cmd can execute any command that outputs credentials in netrc format:

# Password manager integration
yt-dlp --netrc-cmd 'pass show yt-dlp/credentials' URL

# Custom script
yt-dlp --netrc-cmd '/path/to/get-credentials.sh {}' URL

The {} placeholder is replaced with the extractor name.

The command must:

Output credentials in netrc format
Return exit code 0 on success
Return non-zero on failure

Browser Cookies

Extract and use cookies from your browser to authenticate:

Supported Browsers

brave
chrome
chromium
edge
firefox
opera
safari
vivaldi
whale

--cookies-from-browser BROWSER[+KEYRING][:PROFILE][::CONTAINER]

Basic Usage
Specific Profile
Linux Keyring
Firefox Container

# Extract from default Firefox profile
yt-dlp --cookies-from-browser firefox URL

# Extract from default Chrome profile
yt-dlp --cookies-from-browser chrome URL

# Extract from Safari
yt-dlp --cookies-from-browser safari URL

# Use specific Chrome profile
yt-dlp --cookies-from-browser chrome:Profile1 URL

# Use Firefox profile by path
yt-dlp --cookies-from-browser firefox:/path/to/profile URL

# Use profile name
yt-dlp --cookies-from-browser firefox:default-release URL

# Specify keyring for Chromium cookies on Linux
yt-dlp --cookies-from-browser chrome+gnomekeyring URL

# Available keyrings:
# - basictext
# - gnomekeyring
# - kwallet
# - kwallet5
# - kwallet6

# Use specific Firefox container
yt-dlp --cookies-from-browser firefox:default::Personal URL

# Use no container
yt-dlp --cookies-from-browser firefox:default::none URL

# Use all containers (default)
yt-dlp --cookies-from-browser firefox URL

You can also export cookies to a file:

# Export cookies to Netscape format
yt-dlp --cookies cookies.txt URL

# Use exported cookies
yt-dlp --cookies /path/to/cookies.txt URL

Browser cookie extraction requires the browser to be closed or may require additional permissions on some systems.

Command Line Authentication

Provide credentials directly via command line:

Basic Authentication

# Username and password
yt-dlp --username USERNAME --password PASSWORD URL

# Short form
yt-dlp -u USERNAME -p PASSWORD URL

# Prompt for password (more secure)
yt-dlp -u USERNAME URL
# yt-dlp will prompt: "PASSWORD:"

Two-Factor Authentication

# Provide 2FA code
yt-dlp -u USERNAME -p PASSWORD --twofactor 123456 URL

# Short form
yt-dlp -u USERNAME -p PASSWORD -2 123456 URL

Video-Specific Password

Some videos require a specific password:

# Video password (not account password)
yt-dlp --video-password VIDEO_PASSWORD URL

Providing passwords on the command line is less secure as they may be visible in shell history. Use netrc files or be prompted for passwords instead.

Adobe Pass Authentication

For sites using Adobe Pass (TV provider authentication):

# List available TV providers
yt-dlp --ap-list-mso

# Authenticate with TV provider
yt-dlp --ap-mso PROVIDER_ID --ap-username USERNAME --ap-password PASSWORD URL

# Example with Spectrum
yt-dlp --ap-mso Spectrum --ap-username user@example.com URL

Client Certificates

For sites requiring SSL/TLS client certificates:

Certificate File

# PEM file with certificate (and optionally private key)
yt-dlp --client-certificate /path/to/cert.pem URL

Separate Key File

# Certificate and separate private key
yt-dlp --client-certificate /path/to/cert.pem \
       --client-certificate-key /path/to/key.pem URL

Encrypted Private Key

# Provide password for encrypted key
yt-dlp --client-certificate cert.pem \
       --client-certificate-key key.pem \
       --client-certificate-password KEY_PASSWORD URL

# Prompt for password
yt-dlp --client-certificate cert.pem \
       --client-certificate-key key.pem URL
# yt-dlp will prompt for password if key is encrypted

Practical Examples

# ~/.netrc
machine youtube login your-email@gmail.com password your-app-password

# Download with authentication
yt-dlp --netrc 'https://www.youtube.com/watch?v=PRIVATE_VIDEO'

Configuration File Setup

Set authentication options in your config file:

# ~/.config/yt-dlp/config

# Always use netrc
--netrc

# Or custom location
--netrc-location ~/.config/yt-dlp/.netrc

Security Best Practices

Secure Netrc Files

# Set restrictive permissions (Unix/Linux/macOS)
chmod 600 ~/.netrc

# Verify permissions
ls -l ~/.netrc
# Should show: -rw------- (owner read/write only)

Avoid Command Line Passwords

# Appears in shell history and process list
yt-dlp -u user -p "my_password" URL

When using --cookies-from-browser, be aware that:

Cookies contain session tokens that could be hijacked
Some sites may track unusual activity
Consider using a dedicated browser profile for downloads

Troubleshooting

Authentication Failures

# Test with verbose output
yt-dlp --verbose --netrc URL

# Check if netrc is being read
yt-dlp --verbose --netrc URL 2>&1 | grep -i netrc

# Verify netrc format
cat ~/.netrc
# Should have: machine <extractor> login <user> password <pass>

# List browser profiles
yt-dlp --cookies-from-browser firefox --verbose URL 2>&1 | grep -i profile

# Close browser before extracting
# Some systems require browser to be closed

# Try different browser
yt-dlp --cookies-from-browser chrome URL

Permission Errors

# Fix netrc permissions
chmod 600 ~/.netrc

# Check file ownership
ls -l ~/.netrc
# Should be owned by you

Extractor Names

Find the correct extractor name:

# List all extractors
yt-dlp --list-extractors | grep -i youtube

# Use lowercase name in netrc
# E.g., "YouTube" becomes "youtube" in .netrc

Advanced Authentication

Multiple Accounts

# Use different netrc files for different accounts
yt-dlp --netrc-location ~/.netrc.personal URL1
yt-dlp --netrc-location ~/.netrc.work URL2

Conditional Authentication

Use shell scripting for conditional auth:

#!/bin/bash
if [[ $1 == *"youtube"* ]]; then
    yt-dlp --netrc "$1"
elif [[ $1 == *"twitch"* ]]; then
    yt-dlp --cookies-from-browser firefox "$1"
else
    yt-dlp "$1"
fi

Session Management

Some sites require session tokens:

# Use cookie file for session persistence
yt-dlp --cookies session.txt --cookies-from-browser firefox URL

# Cookies are updated in the file for next use

Getting Started

Core Concepts

Guides

Advanced

Reference

​Authentication Methods

​Using Netrc Files

​Creating a Netrc File

​Netrc File Format

​Example Netrc File

​Enabling Netrc Authentication

​Netrc in Configuration File

​Encrypted Netrc with GPG

​Create Encrypted Netrc

​Use Encrypted Netrc

​Custom Netrc Command

​Browser Cookies

​Supported Browsers

​Cookie Extraction Syntax

​Cookie File Export

​Command Line Authentication

​Basic Authentication

​Two-Factor Authentication

​Video-Specific Password

​Adobe Pass Authentication

​Client Certificates

​Certificate File

​Separate Key File

​Encrypted Private Key

​Practical Examples

​Configuration File Setup

​Security Best Practices

​Secure Netrc Files

​Avoid Command Line Passwords

​Browser Cookie Security

​Troubleshooting

​Authentication Failures

​Cookie Extraction Issues

​Permission Errors

​Extractor Names

​Advanced Authentication

​Multiple Accounts

​Conditional Authentication

​Session Management

Authentication Methods

Using Netrc Files

Creating a Netrc File

Netrc File Format

Example Netrc File

Enabling Netrc Authentication

Netrc in Configuration File

Encrypted Netrc with GPG

Create Encrypted Netrc

Use Encrypted Netrc

Custom Netrc Command

Browser Cookies

Supported Browsers

Cookie Extraction Syntax

Cookie File Export

Command Line Authentication

Basic Authentication

Two-Factor Authentication

Video-Specific Password

Adobe Pass Authentication

Client Certificates

Certificate File

Separate Key File

Encrypted Private Key

Practical Examples

Configuration File Setup

Security Best Practices

Secure Netrc Files

Avoid Command Line Passwords

Browser Cookie Security

Troubleshooting

Authentication Failures

Cookie Extraction Issues

Permission Errors

Extractor Names

Advanced Authentication

Multiple Accounts

Conditional Authentication

Session Management