# ytdl-patched: a yt-dlp fork with extra extractors and a long tail of mirrors

> ytdl-patched is a fork of yt-dlp that adds long filename handling on Unix systems, self-hosted video service support, comment subtitles and a set of new extractors, maintained by a single contributor who mirrors the repository across a dozen forges. The README carries an explicit disclaimer that there is no absolute warranty and that you should use yt-dlp if you prefer it.

**ytdl-patched/ytdl-patched** — yt-dlp fork with some more features

- Repository: https://github.com/ytdl-patched/ytdl-patched
- Website: https://github.com/yt-dlp/yt-dlp
- Stars: 633 · Forks: 57
- Language: Python
- License: Unlicense
- Published: 2026-10-21 · Updated: 2026-10-21 · Language: en
- Canonical page: https://hysenlabs.com/projects/ytdl-patched-ytdl-patched

## A fork with a disclaimer attached

ytdl-patched is a youtube-dl fork based on yt-dlp, and the repository description says it plainly: a yt-dlp fork with some more features. The default branch is named ytdlp, the homepage points at the upstream yt-dlp repository rather than a fork specific site, and the licence is the Unlicense, the same public domain dedication upstream uses.

The disclaimer at the end of the introduction is the most important line in the README for an adopter: ytdl-patched does exist for my use, so there is no absolute warranty for anything, and if you do not like it, use yt-dlp.

That framing is unusual and worth taking at face value. This is one maintainer's working copy with additions he needed, published for others to use. There is no compatibility promise, no support commitment and no statement about how long the fork will exist.

The mirrors section shows the same reality from a different angle. There is a primary mirror on GitHub, the previous GitHub repository is struck through as passed away, and then a list of secondary mirrors on Bitbucket, a personal forge, GitLab, Gitea, SourceHut, Codeberg, GitGud and a Keybase account, plus two personal pages that are marked as just for fun and no longer synced. One of the secondary mirrors notes that it is manually mirrored at every git push.

For someone evaluating this, that mirror list is a risk register. A single maintainer with a dozen copies of the same code is a single point of failure, and the fact that some copies are already out of sync is a live demonstration.

## The upstream merge is a workflow, and it can fail

The status table near the top of the README lists three GitHub Actions workflows, and one of them is the interesting one.

There is a workflow for tests, a workflow for build and release, and a workflow for merging commits from upstream, and that last one carries a note in the status column that reads: there's conflict if it fails. The note in the table says the same thing in a longer form.

So the fork stays current through automation rather than through a maintainer merging by hand, and when upstream yt-dlp changes something that conflicts with a patch here, the merge workflow stops. Whether the maintainer then resolves it or the branch simply falls behind is not something the README explains, and that is exactly the kind of detail you need when you are deciding whether to depend on the fork.

The repository root shows the same shape as upstream yt-dlp, since it is a fork of it. There is the yt_dlp package directory, devscripts, docker, docs, test, icons, a b directory, setup.py and setup.cfg, pyproject.toml, MANIFEST.in, a Makefile, requirements.txt, supportedsites.md, Changelog.md, CONTRIBUTORS, Collaborators.md, a public.key file, pyinst.py, and a wd.cmd file.

The release tags follow a different convention from upstream, and the recent ones make the pace obvious. They are named by date and build number, 2024.09.08.1725764184, 2024.09.01.1725160089 and 2024.08.25.1724554306, so the tagged history in this repository stops in September 2024 even though the last push to the branch was on 2026-10-18.

## Long filenames, and the Unix 255 byte limit

The first new feature listed is long name escaping for Unix systems. If the filename of a downloaded video can get longer than 255 bytes in the system locale, the fork prevents it from exceeding that length by splitting the name into 255 byte pieces.

The reason this exists is a filesystem limit rather than a fashion choice, and it is the kind of bug that only shows up on long titles. The README is candid about the downside: treating split names requires special scripts just for that. So the feature converts a hard failure, a download that cannot be written, into a soft one, a file that needs reassembling.

The second item in the list is a fix rather than a feature, and it is worth understanding because it describes a class of runaway process. The Generic Extractor used to return at the first website match; now it collects matched websites and returns them as a playlist, creating a nested playlist that may cause an infinite loop. The change makes the extractor return everything it matched instead of stopping at the first hit, which is the more complete behaviour, and the infinite loop risk it mentions is the failure mode of the alternative.

Both of these are the kind of change that comes from running the tool for years against real sites rather than from a design document, and that is a fair signal about the project in general.

## Self-hosted video services and the instance discovery flags

The Generic Extractor Extended section is the longest feature block, and it covers two different kinds of work.

The first is redirect resolution. A set of Japanese BBS redirect domains, pinktower.com, jump.5ch.net and jump.megabbs.info, is resolved automatically to its destination, as are Pixiv redirects and Firebase Dynamic Links on domains ending with .page.link. The README notes that for Pixiv it is still looking for test cases for mutated URLs, which is an honest statement of an unfinished edge.

The second is self-hosted service support for Mastodon, PeerTube and Misskey. For these, the fork contains a large list of instances, and you can opt in to instance checking in case your instance is not in the list. The three flags are named per service, `--check-mastodon-instance`, `--check-peertube-instance` and `--check-misskey-instance`, and they are passed on the command line like any other option.

This is the feature that most justifies the fork existing. A self-hosted instance has to be discovered, and a hardcoded list goes stale, so the opt-in check queries the service for instances it does not know about. The cost of that choice is a network request per session, which is why it is opt-in rather than the default.

The rest of the feature list is extractor additions. The README names askmona and askmona3, disneychris, dnatube, fc2:user for FC2 user uploaded videos, iwara:user, javhub, a group that scrapes the question and answer section of a site to find video URLs, and the mastodon, misskey and related variants for users and numeric user ids. The README notes that broken and incomplete extractors are not listed.

For anyone whose content lives on a small self-hosted instance, this is the reason to use the fork rather than upstream.

## NicoNico comments as subtitles

The remaining headline feature is downloading NicoNico comments as a subtitle track, with no dependency required.

The minimum flags are `--sub-format ass --write-subs`, and to embed the comments into the video file the README gives the fuller combination `--sub-format ass --write-subs --embed-subs --remux-video mkv`.

The reason the format is ass, Advanced SubStation Alpha, is that comments are positioned text with styling, and plain subtitle formats such as srt cannot express that. The remux to mkv is needed because embedding a styled subtitle track into an mp4 container is not something the muxers handle cleanly.

So the feature is a small pipeline rather than a single switch, and it costs you a remux and a specific container. It is also a good illustration of the kind of niche, site specific work this fork exists for.

The other listed addition is the new extractors, and the README is careful to say the list is not exhaustive, since broken and incomplete ones are left out. That is the honest framing: the fork carries community contributed extractors of varying quality, and the README does not claim otherwise.

## The build and dependency surface

The build machinery is inherited from upstream and the files are visible in the repository.

The requirements are short:

```python
mutagen
pycryptodomex
websockets
brotli; platform_python_implementation=='CPython'
brotlicffi; platform_python_implementation!='CPython'
certifi
```

The two brotli entries are an environment split, with the compiled brotli wheel for CPython and the pure Python brotlicffi fallback everywhere else, which is the kind of detail that only appears when a project supports unusual interpreters.

The Makefile gives the top level targets:

```make
all: lazy-extractors ytdl-patched doc pypi-files
clean: clean-test clean-dist
clean-all: clean clean-cache
completions: completion-bash completion-fish completion-zsh
```

There are also ot and offlinetest targets, the latter being the offline test suite, plus tar for a source tarball and pypi-files for assembling the files listed in MANIFEST.in. The clean-test target removes a long list of partial download artefacts, which tells you how many formats and containers the tool can produce.

The setup.py file describes the package as a youtube-dl fork with additional features and patches, reads the version and requirements from the repository at build time, and carries a py2exe configuration for a Windows console build, with a warning that py2exe builds do not support pycryptodomex and need VC++14, and that pyinst.py should be used with pyinstaller instead.

The licence situation is the easiest part of the decision. The Unlicense places the code in the public domain, so there is no attribution or copyleft obligation to carry into a project that uses it.

## Conclusion

Adopt ytdl-patched if you specifically need one of its additions, such as instance discovery for Mastodon, PeerTube or Misskey, comment subtitles from NicoNico, or the handling of filenames that exceed the 255 byte Unix limit. Do not adopt it as a general yt-dlp replacement, because the README itself recommends yt-dlp to anyone who is not sure, and the fork is maintained by one person with no release warranty. Verify first which upstream yt-dlp release your copy contains, since the fork is merged forward by a workflow that the README warns can fail with a conflict, and pin a commit rather than tracking the branch if you depend on a specific behaviour.

## FAQ

### What is ytdl-patched and how does it relate to yt-dlp?

It is a fork of yt-dlp, itself a fork of youtube-dl, described in the repository as a yt-dlp fork with some more features. It is maintained by a single contributor, mirrored across several forges, and the README recommends using yt-dlp if you prefer it.

### What new features does ytdl-patched add over yt-dlp?

The README lists long name escaping for Unix systems where a filename would exceed 255 bytes, an extended Generic Extractor that resolves redirects and supports self-hosted Mastodon, PeerTube and Misskey instances, and NicoNico comments downloadable as subtitles, plus a set of new extractors.

### How does ytdl-patched stay up to date with upstream yt-dlp?

Through a GitHub Actions workflow for merging commits from upstream, alongside separate workflows for tests and for build and release. The status table notes that there is a conflict if the merge fails.

### How do I fetch comments as subtitles with ytdl-patched?

Use the flags --sub-format ass --write-subs to download NicoNico comments as a subtitle track, and add --embed-subs --remux-video mkv to embed them into the video file. The README states no extra dependency is required for this feature.

## Sources

- [License: Unlicense](https://github.com/ytdl-patched/ytdl-patched/blob/ytdlp/LICENSE)
- [Project website](https://github.com/yt-dlp/yt-dlp)
- [README](https://github.com/ytdl-patched/ytdl-patched/blob/ytdlp/README.md)
- [Releases](https://github.com/ytdl-patched/ytdl-patched/releases)
- [ytdl-patched/ytdl-patched on GitHub](https://github.com/ytdl-patched/ytdl-patched)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/ytdl-patched-ytdl-patched