Install & Compatibility
Where this runs
tested against v10.9.0 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.920 runs
installs and imports cleanly · install 0.0s · import 0.767s · 248.1MB
glibcpy 3.10–3.920 runs
installs and imports cleanly · install 6.7s · import 0.692s · 240MB
243MB installed
● package 243MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
YouTube
✓ from pytubefix import YouTube
Playlist
✓ from pytubefix import Playlist
Search
✓ from pytubefix import Search
on_progress
✓ from pytubefix.cli import on_progress
VideoUnavailable
✓ from pytubefix.exceptions import VideoUnavailable
This quickstart example demonstrates how to download a YouTube video using `pytubefix`. It initializes a `YouTube` object with a video URL, registers a progress callback for real-time updates, retrieves the video's metadata, and then downloads the highest resolution progressive stream to a 'downloads' directory. It handles a placeholder URL and basic error reporting.
import os
from pytubefix import YouTube
def on_progress(stream, chunk, bytes_remaining):
total_size = stream.filesize
bytes_downloaded = total_size - bytes_remaining
percentage_of_completion = bytes_downloaded / total_size * 100
print(f"\rDownloading: {percentage_of_completion:.2f}%", end='')
video_url = os.environ.get('YOUTUBE_VIDEO_URL', 'https://www.youtube.com/watch?v=dQw4w9WgXcQ') # Rick Astley - Never Gonna Give You Up
try:
yt = YouTube(video_url, on_progress_callback=on_progress)
print(f"\nTitle: {yt.title}")
print(f"Author: {yt.author}")
print(f"Views: {yt.views}")
# Get the highest resolution progressive stream
# Progressive streams contain both video and audio
stream = yt.streams.get_highest_resolution()
if stream:
print(f"Downloading '{yt.title}' in {stream.resolution}...")
stream.download(output_path='./downloads')
print("\nDownload complete!")
else:
print("No suitable progressive stream found.")
except Exception as e:
print(f"\nAn error occurred: {e}")
pytubefix --version
Debug
Known issues
breakingYouTube's internal APIs change frequently, which can cause `pytubefix` functionality to break without warning. While `pytubefix` is actively maintained, users should expect occasional disruptions.fixRegularly update `pytubefix` to the latest version (`pip install --upgrade pytubefix`) to receive patches for YouTube's API changes. Wrap download operations in `try-except` blocks for graceful error handling.
affects: All versions, due to external API changes
gotchaAccessing age-restricted content or private videos often requires OAuth authentication. If `allow_oauth_cache=False` (default for some operations), you may be prompted repeatedly for authentication.fixWhen creating a `YouTube` object, set `use_oauth=True` and `allow_oauth_cache=True` to authenticate and cache tokens, reducing repeated prompts. `yt = YouTube(url, use_oauth=True, allow_oauth_cache=True)`.
affects: All versions
gotchaLive streams typically cannot be downloaded until after they have concluded. Trying to download an active or recently finished live stream may result in errors or `LiveStreamEnded` exceptions.fixWait until the live stream has ended, sometimes several hours or days, before attempting to download. Implement specific exception handling for `LiveStreamEnded` or `VideoUnavailable`.
affects: All versions
breakingOlder versions (prior to v10.1.1 and v10.3.3) could encounter `TypeError` when accessing attributes like `.length` or find `yt.title` and `yt.duration` as bound methods instead of properties.fixUpgrade to `pytubefix` version 10.3.3 or newer to resolve issues where `title`, `duration`, or `length` might be incorrectly retrieved or raise `TypeError`. (`pip install --upgrade pytubefix`)
affects: <10.1.1, <10.3.3
Errors
Common errors & fixes
pytubefix.exceptions.VideoUnavailable: {video_id} is unavailable
The video is private, deleted, region-locked, or YouTube's API structure changed, preventing `pytubefix` from accessing it.
fixVerify the video URL is correct and the video is publicly accessible. Try updating `pytubefix` (`pip install --upgrade pytubefix`). For region-locked content, consider using proxies. Wrap calls in `try-except VideoUnavailable` for graceful handling.
HTTP Error 410: Gone
YouTube has changed its internal API, rendering the current parsing logic in `pytubefix` obsolete for that specific video or stream. Often happens when YouTube deprecates old stream manifest formats.
fixUpdate `pytubefix` to the latest version (`pip install --upgrade pytubefix`). This error frequently indicates that a new patch has been released to accommodate YouTube's changes.
pytubefix.exceptions.AgeRestrictedError: {video_id} is age restricted, and can't be accessed without logging in.
Attempting to download an age-restricted video without providing OAuth credentials.
fixInstantiate `YouTube` with OAuth enabled: `yt = YouTube(url, use_oauth=True, allow_oauth_cache=True)`. This will prompt for browser authentication and cache the token.
KeyError: 'videoDetails' or other dictionary key
YouTube frequently changes the keys in its JSON responses for video metadata, causing `pytubefix` to fail when parsing the data.
fixThis typically requires a `pytubefix` library update. Install the latest version (`pip install --upgrade pytubefix`) to get the fix for the changed dictionary keys.
Upgrade
Version history
10.9.0latest on PyPI · released Jun 3, 2026
Audit
Dependencies
nodejsoptionalRequired for automatic PO Token generation, which helps bypass bot detection and some age restrictions. The library attempts to locate `node` in the system PATH.