# What Library Is Pyutube Built Upon? The pytubefix Architecture Explained

> Discover the library Pyutube uses. Pyutube employs pytubefix, a robust fork of the original pytube, for YouTube streaming, downloading, and metadata extraction.

- Repository: [Ebraheem Alhetari/pyutube](https://github.com/hetari/pyutube)
- Tags: internals
- Published: 2026-03-03

---

**Pyutube is built upon pytubefix**, a maintained fork of the original pytube library that handles all core YouTube interactions including streaming, downloading, and metadata extraction through its `YouTube` and `Playlist` classes.

The open-source command-line tool **Pyutube** (`hetari/pyutube`) provides a user-friendly interface for downloading YouTube videos, audio, and playlists. What library is Pyutube built upon to deliver this functionality? Under the hood, it relies entirely on **pytubefix** to interface with YouTube's streaming infrastructure, delegating every search query, stream selection, and file download to this underlying dependency.

## The Foundation: pytubefix

**pytubefix** is a community-maintained fork of the original `pytube` library, created to address ongoing API changes and maintenance issues with YouTube's platform. Unlike standalone tools, Pyutube does not implement its own YouTube scraping logic; instead, it imports and orchestrates classes from `pytubefix` to handle HTTP requests, stream parsing, and adaptive bitrate selection.

In [`setup.py`](https://github.com/hetari/pyutube/blob/main/setup.py), the project explicitly declares this dependency in `install_requires`:

```python
install_requires=[
    'pytubefix',
    # additional dependencies...

]

```

This ensures that installing Pyutube automatically pulls in the `pytubefix` package that performs the actual network operations.

## Architectural Layers: How Pyutube Wraps pytubefix

Pyutube's codebase is organized into distinct layers that abstract `pytubefix` functionality into CLI commands and service workflows.

### CLI Entry Point

In [`pyutube/cli.py`](https://github.com/hetari/pyutube/blob/main/pyutube/cli.py), the application parses command-line arguments and launches appropriate handlers. Rather than implementing YouTube logic directly, it instantiates service classes that internally import from `pytubefix`. This separation keeps the CLI layer focused on user interaction while delegating all YouTube-specific operations to the underlying library.

### Service Layer Implementation

The service layer in `pyutube/services/` contains the core download logic and demonstrates direct `pytubefix` integration:

- **[`pyutube/services/VideoService.py`](https://github.com/hetari/pyutube/blob/main/pyutube/services/VideoService.py)**: Imports `YouTube` from `pytubefix` to create video objects and manage stream selection workflows
- **[`pyutube/services/DownloadService.py`](https://github.com/hetari/pyutube/blob/main/pyutube/services/DownloadService.py)**: Handles generic download operations using `pytubefix` classes
- **[`pyutube/services/AudioService.py`](https://github.com/hetari/pyutube/blob/main/pyutube/services/AudioService.py)**: Manages audio-only extraction paths through the same underlying API
- **[`pyutube/services/FileService.py`](https://github.com/hetari/pyutube/blob/main/pyutube/services/FileService.py)**: Imports `safe_filename` from `pytubefix.helpers` to sanitize output filenames

For example, [`pyutube/services/VideoService.py`](https://github.com/hetari/pyutube/blob/main/pyutube/services/VideoService.py) contains the following import pattern used throughout the service:

```python
from pytubefix import YouTube

# Within the VideoService class

video = YouTube(url, use_oauth=self.use_oauth)

```

### Playlist and Utility Integration

In [`pyutube/handlers/PlaylistHandler.py`](https://github.com/hetari/pyutube/blob/main/pyutube/handlers/PlaylistHandler.py), Pyutube imports `Playlist` directly from `pytubefix` to iterate through multi-video URLs:

```python
from pytubefix import Playlist

```

Additionally, [`pyutube/utils.py`](https://github.com/hetari/pyutube/blob/main/pyutube/utils.py) retrieves the installed `pytubefix` version for compatibility checking and auto-update routines:

```python
from pytubefix import __version__ as pytubefix_version

```

This allows Pyutube to verify that users have a functional version of the underlying library and prompt for updates when necessary.

## Working With the Underlying Library

Because Pyutube is built upon `pytubefix`, advanced users can leverage the same objects directly for custom scripting or inspect how the wrapper utilizes the API.

### Command-Line Usage

The simplest way to use the tool is through its CLI, which internally calls `pytubefix` methods:

```bash

# Download a YouTube video as the highest-quality MP4

pyutube https://www.youtube.com/watch?v=dQw4w9WgXcQ

```

### Direct pytubefix Access

For implementations bypassing the CLI wrapper, import the identical classes that Pyutube uses internally:

```python
from pytubefix import YouTube

# Create a YouTube object using the same API called by VideoService.py

yt = YouTube(
    "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
    use_oauth=True,
    allow_oauth_cache=True,
)

# List available adaptive video streams (separate video/audio)

for stream in yt.streams.filter(progressive=False, adaptive=True, mime_type="video/mp4"):
    print(stream.resolution, stream.filesize)

# Download the best progressive stream (contains both video and audio)

yt.streams.get_highest_resolution().download(output_path="downloads")

```

### Advanced Service Integration

You can also leverage Pyutube's own service classes, which expose the underlying `pytubefix` streams for advanced workflows like merging separate video and audio files:

```python
from pyutube.services.VideoService import VideoService

service = VideoService(
    url="https://www.youtube.com/watch?v=dQw4w9WgXcQ",
    quality="720p",
    path="./my_downloads"
)

# search_process internally uses pytubefix's YouTube class

video = service.search_process()
streams, audio, chosen_quality = service.get_selected_stream(video)

# Download separate video and audio streams (adaptive format)

video_stream = service.get_video_streams(chosen_quality, streams)
video_stream.download(output_path=service.path)

audio_stream = audio
audio_stream.download(output_path=service.path, filename="audio.mp3")

# Merge using moviepy (optional post-processing)

service.merging(
    video_name=video_stream.default_filename,
    audio_name=audio_stream.default_filename
)

```

## Summary

- **Pyutube is built upon pytubefix**, a maintained fork of the pytube library that interfaces directly with YouTube's streaming infrastructure.
- All core functionality in `pyutube/services/`—including [`VideoService.py`](https://github.com/hetari/pyutube/blob/main/VideoService.py), [`DownloadService.py`](https://github.com/hetari/pyutube/blob/main/DownloadService.py), and [`AudioService.py`](https://github.com/hetari/pyutube/blob/main/AudioService.py)—imports classes directly from `pytubefix`.
- The CLI entry point in [`pyutube/cli.py`](https://github.com/hetari/pyutube/blob/main/pyutube/cli.py) delegates to service classes rather than implementing YouTube logic directly.
- [`setup.py`](https://github.com/hetari/pyutube/blob/main/setup.py) explicitly lists `pytubefix` as a required dependency, while [`pyutube/utils.py`](https://github.com/hetari/pyutube/blob/main/pyutube/utils.py) checks its version for update compatibility.
- [`pyutube/handlers/PlaylistHandler.py`](https://github.com/hetari/pyutube/blob/main/pyutube/handlers/PlaylistHandler.py) relies on `pytubefix.Playlist` for multi-video downloads, and [`pyutube/services/FileService.py`](https://github.com/hetari/pyutube/blob/main/pyutube/services/FileService.py) uses `pytubefix.helpers.safe_filename` for file sanitization.
- Users can access `pytubefix` objects directly for custom scripts or use Pyutube's wrapper classes for streamlined terminal-based workflows.

## Frequently Asked Questions

### Is Pyutube the same as pytubefix?

No. Pyutube is a command-line interface and service wrapper built on top of pytubefix. While **pytubefix** handles the low-level HTTP requests, stream extraction, and YouTube API parsing, Pyutube provides the terminal interface, argument parsing, and post-processing features like video/audio merging via `moviepy`.

### Why does Pyutube use pytubefix instead of the original pytube?

Pyutube uses **pytubefix** because it is an actively maintained fork of the original pytube library. The original pytube project has experienced maintenance delays, while pytubefix incorporates rapid fixes for YouTube's frequent API changes, cipher updates, and anti-bot measures. This ensures Pyutube remains functional as YouTube updates its platform.

### Can I use pytubefix directly without installing Pyutube?

Yes. Since Pyutube is built upon **pytubefix**, you can import and use `pytubefix` directly in your Python scripts without installing Pyutube. Simply run `pip install pytubefix` and import `YouTube` or `Playlist` from the package, exactly as implemented in [`pyutube/services/VideoService.py`](https://github.com/hetari/pyutube/blob/main/pyutube/services/VideoService.py) and [`pyutube/handlers/PlaylistHandler.py`](https://github.com/hetari/pyutube/blob/main/pyutube/handlers/PlaylistHandler.py).

### Where does Pyutube declare its dependency on pytubefix?

Pyutube declares **pytubefix** as a runtime dependency in [`setup.py`](https://github.com/hetari/pyutube/blob/main/setup.py) within the `install_requires` list. Additionally, [`pyutube/utils.py`](https://github.com/hetari/pyutube/blob/main/pyutube/utils.py) imports `__version__` from `pytubefix` to verify the installed version during Pyutube's initialization and auto-update routines, ensuring compatibility between the wrapper and the underlying library.