Skip to main content

Installing Plugins for yt-dlp

Plugins extend yt-dlp's functionality by adding new extractors and post-processors. This guide covers the various methods for installing and managing plugins safely and effectively.

Understanding yt-dlp Plugins​

Plugin Types​

  • Extractor plugins: Add support for new websites and services
  • Post-processor plugins: Add custom processing capabilities

Plugin Structure​

Plugins use Python's namespace package system:

yt_dlp_plugins/
    extractor/
        my_extractor.py
    postprocessor/
        my_processor.py

Installation Methods​

User-Level Installation​

Linux/macOS:

# Create plugin directory
mkdir -p ~/.config/yt-dlp/plugins/myplugin

# Install plugin package
cp -r yt_dlp_plugins ~/.config/yt-dlp/plugins/myplugin/

Windows:

# Create plugin directory
mkdir "%APPDATA%\yt-dlp\plugins\myplugin"

# Copy plugin files
xcopy yt_dlp_plugins "%APPDATA%\yt-dlp\plugins\myplugin\yt_dlp_plugins" /E

Alternative User Directories​

# Alternative user plugin locations
~/.yt-dlp/plugins/myplugin/yt_dlp_plugins/
~/yt-dlp-plugins/myplugin/yt_dlp_plugins/
${XDG_CONFIG_HOME}/yt-dlp-plugins/myplugin/yt_dlp_plugins/

System-Wide Installation​

# System directories (requires admin rights)
sudo mkdir -p /etc/yt-dlp/plugins/myplugin
sudo cp -r yt_dlp_plugins /etc/yt-dlp/plugins/myplugin/

2. Executable Location Installation​

For portable installations:

# Binary installations
# Place in same directory as yt-dlp executable
./yt-dlp-plugins/myplugin/yt_dlp_plugins/

# Source installations  
# Place relative to yt_dlp source directory
./yt-dlp-plugins/myplugin/yt_dlp_plugins/

3. pip Installation​

Install from PyPI​

# Install published plugin
pip install yt-dlp-my-plugin

# Install with user flag
pip install --user yt-dlp-my-plugin

# Install development version
pip install git+https://github.com/author/yt-dlp-my-plugin.git

Install from Local Source​

# Install from local directory
pip install ./my-plugin-directory

# Install in development mode
pip install -e ./my-plugin-directory

4. Archive Installation​

Install from .zip, .egg, or .whl files:

# Place archive in plugin directory
cp myplugin.zip ~/.config/yt-dlp/plugins/

# Archive should contain yt_dlp_plugins/ in root
unzip -l myplugin.zip
# Archive: myplugin.zip
#   yt_dlp_plugins/extractor/myextractor.py
#   yt_dlp_plugins/postprocessor/myprocessor.py

Plugin Discovery and Loading​

Check Loaded Plugins​

# Run with verbose output to see loaded plugins
yt-dlp --verbose "https://example.com/test"

# Look for plugin loading messages:
# [debug] Loading yt_dlp_plugins.extractor.myextractor

Disable Plugin Loading​

# Disable all plugins
YTDLP_NO_PLUGINS=1 yt-dlp "https://example.com/video"

# Set environment variable permanently
export YTDLP_NO_PLUGINS=1

Managing Multiple Plugins​

Plugin Directory Structure​

~/.config/yt-dlp/plugins/
├── plugin1/
│   └── yt_dlp_plugins/
│       ├── extractor/
│       │   └── site1.py
│       └── postprocessor/
│           └── processor1.py
├── plugin2/
│   └── yt_dlp_plugins/
│       └── extractor/
│           └── site2.py
└── plugin3.zip

Plugin Precedence​

  • Extractor plugins take priority over built-in extractors
  • Multiple plugins can coexist
  • Plugin loading order affects priority

Plugin Security​

Security Considerations​

  • Code review: Always review plugin code before installation
  • Source trust: Only install plugins from trusted sources
  • Permissions: Plugins run with full yt-dlp permissions
  • Updates: Keep plugins updated for security fixes

Safe Installation Practices​

# Review plugin code before installation
unzip -l plugin.zip
cat yt_dlp_plugins/extractor/example.py

# Test in isolated environment first
python -m venv test_env
source test_env/bin/activate
pip install ./plugin

Official Plugin Resources​

Finding Plugins​

# Search GitHub for yt-dlp plugins
# Look for repositories with topic: yt-dlp-plugins

Plugin Naming Conventions​

  • Follow yt-dlp-plugins topic on GitHub
  • Use descriptive plugin names
  • Include version information

Troubleshooting Plugin Installation​

Common Issues​

Plugin Not Loading​

# Check plugin directory structure
ls -la ~/.config/yt-dlp/plugins/myplugin/

# Verify namespace package structure
find ~/.config/yt-dlp/plugins/ -name "*.py" -type f

Import Errors​

# Check Python path issues
python -c "import yt_dlp_plugins.extractor.myextractor"

# Verify plugin dependencies
pip list | grep -i required-dependency

Plugin Conflicts​

# Test with specific plugin only
# Temporarily move other plugins
mv ~/.config/yt-dlp/plugins/other_plugin ~/.config/yt-dlp/plugins/other_plugin.disabled

Debug Plugin Loading​

# Maximum verbosity for plugin debugging
yt-dlp -vv --print-traffic "https://test-url"

# Check for plugin-related error messages
yt-dlp --verbose 2>&1 | grep -i plugin

Plugin Development Setup​

Development Environment​

# Clone sample plugin repository
git clone https://github.com/yt-dlp/yt-dlp-sample-plugins.git

# Install in development mode
cd yt-dlp-sample-plugins
pip install -e .

# Test plugin functionality
yt-dlp --verbose "test://video"

Testing Plugins​

# Test extractor plugin
yt-dlp --list-extractors | grep -i myplugin

# Test post-processor plugin
yt-dlp --use-postprocessor MyProcessor "https://example.com/video"

Plugin Maintenance​

Updating Plugins​

# Update pip-installed plugins
pip install --upgrade yt-dlp-my-plugin

# Update manually installed plugins
# Download new version and replace old files

Removing Plugins​

# Remove pip-installed plugins
pip uninstall yt-dlp-my-plugin

# Remove manually installed plugins
rm -rf ~/.config/yt-dlp/plugins/myplugin