How to Use TubeArchivist: The Beginner's Guide (First Deploy, First Subscription, the Cookies Lesson, and the Jellyfin Hand-Off)

CodexFuse Team · 2026-11-01T12:19:29.454Z · 13 min read

Learn how to use TubeArchivist: deploy the three-container stack, fix downloads with the cookies lesson, subscribe your first channel, search subtitles, enable SponsorBlock, and hand the archive to Jellyfin.

If you want to learn how to use TubeArchivist, start here: TubeArchivist is a self-hosted, open-source media server that downloads YouTube channels and playlists, indexes every subtitle and comment, and gives you a fully searchable private library you control. This tubearchivist tutorial walks you through the whole arc in one place: the three-container Docker deploy, the first login, the cookies lesson that fixes most failed downloads, your first channel subscription, the searchable-subtitles payoff, SponsorBlock, family sharing, and the Jellyfin hand-off. If you are new to containers, read our Docker beginner guide first, because everything in this guide runs on Docker.

One important note before you start: this guide is about TubeArchivist (github.com/tubearchivist/tubearchivist, GPL-3.0, roughly 8,500 GitHub stars), the self-hosted archive project from developer bbilly1. It is not TubeArchiver (tubearchiver.com), an unrelated commercial desktop app that currently ranks on the same search page. They share a name root and nothing else. Also keep the framing honest: archive videos you own, that are public domain, or that you have the rights to keep — your own uploads are the obvious case.

What Is TubeArchivist?

TubeArchivist is a self-hosted, open-source media server that builds your own personal YouTube archive. You subscribe to channels or playlists, it downloads the videos with yt-dlp, and it indexes everything — titles, descriptions, subtitles, and comments — into Elasticsearch so your whole collection becomes fully searchable. The project is GPL-3.0 licensed, has been in development since 2021, and released version 0.6.0 on October 25, 2026. Think of it as your own private YouTube that works offline and never deletes a video out from under you. That is the core promise of a self hosted youtube archive: the platform can remove, demonetize, or geo-block a video, and your copy stays exactly where you left it.

Under the hood it is a three-container Docker stack. The main app container serves the web interface and the API, Redis holds the download queue and session data, and Elasticsearch stores the searchable index of videos, subtitles, and comments. Knowing those three pieces matters, because most beginner problems are really just one of the three containers being unhappy — usually Elasticsearch, which is the heaviest and the pickiest of the three.

What Do I Need Before the TubeArchivist Setup?

You need a machine with Docker and Docker Compose, about 2 GB of free memory for a small test setup or around 4 GB for a mid-to-large library, a dual-core CPU with four threads as a minimum, and real disk space — video archives grow fast. If you are deploying on rented hardware rather than a home NAS, our what is VPS hosting guide explains the basics, and you should know the official guidance: TubeArchivist needs around 2 GB of available memory for a small testing setup and around 4 GB for a mid to large sized installation.

Two host-level details trip up first-timers, so handle them before you deploy. First, Elasticsearch requires the kernel setting vm.max_map_count to be at least 262144 on the host — run sudo sysctl -w vm.max_map_count=262144 to set it. Second, if you bind-mount folders into the stack instead of using named volumes, Elasticsearch writes files as UID 1000 and GID 0, so set ownership with chown 1000:0 -R /path/to/mount/point or the ES container will fail to start. The third detail is disk headroom: Elasticsearch flips its index to read-only if disk usage passes 95 percent, and it only unlocks again once usage drops below 90 percent — leave generous free space on your archive drive.

How Do I Install TubeArchivist with Docker?

The tubearchivist docker deploy is the official path, and it takes about eight steps from an empty folder to a working archive. Grab the official docker-compose.yml from the TubeArchivist GitHub repo (the file lives at the repo root on the develop branch), put it in a project folder, and work through this arc.

1. Create a project folder and drop the official docker-compose.yml into it.
2. Set the required environment variables: TA_HOST (the URL you will open in the browser, e.g. http://tubearchivist.local:8000), TA_USERNAME and TA_PASSWORD (your first account), REDIS_CON (redis://archivist-redis:6379), ES_URL (http://archivist-es:9200), and ELASTIC_PASSWORD. TA_PORT is optional and changes the listening port from the default 8000.
3. On the host, run sudo sysctl -w vm.max_map_count=262144 so Elasticsearch can start.
4. If you use bind mounts, chown 1000:0 -R on the mounted folders.
5. Start the stack with docker compose up -d. All three containers — tubearchivist, archivist-redis, archivist-es — should reach a healthy state.
6. Wait for the first-start migrations. On first boot TubeArchivist runs database and index migrations that take a few minutes depending on your hardware — do not panic-restart the container during this window.
7. Open your TA_HOST URL in the browser. If you see Bad Request (400), your TA_HOST value does not match the origin you are browsing from — fix the variable and restart.
8. Log in with TA_USERNAME and TA_PASSWORD. That first account automatically gets superuser privileges, so pick a strong password and never leave the defaults on a machine reachable from the internet.

Two notes on the current stack. Since version 0.6.0 the bundled nginx server is gone — the application serves media and artwork directly on port 8000 via uvicorn. And the Elasticsearch side changed: the bundled bbilly1/tubearchivist-es image is amd64-only, so on ARM64 hardware (like a Raspberry Pi) you should use the official Elasticsearch 9.5.5 image instead — the compose file even carries that hint as a comment. The official install docs still mention Elasticsearch 8 in places, but the v0.6.0 release notes document the 8.19.0 to 9.5.5 update path, so treat the release notes as current.

Why Do My Downloads Fail? The TubeArchivist Cookies Lesson

Most failed TubeArchivist downloads are not a bug — they are YouTube's bot detection. Datacenter IP ranges and VPN exit IPs are more likely to trip bot detection or get blocked outright, and the symptoms are unmistakable: a "Sign in to confirm you're not a bot" message, HTTP Error 403: Forbidden, or your download speed suddenly collapsing to a few kilobytes per second. The fix is importing your YouTube cookie into TubeArchivist so yt-dlp can prove it is a real browser session. Community advice (for example the Railway deploy guide) suggests using a throwaway Google account for this — that wording does not come from the official docs, so treat it as community best practice, not official guidance.

Importing your YouTube cookie into TubeArchivist allows yt-dlp to bypass age restrictions, gives access to private videos, and unlocks your Watch Later or Liked Videos playlists. The easiest import path is the Tube Archivist Companion browser extension for Firefox and Chrome: install it, log into YouTube in that browser, and the extension hands the cookie to TubeArchivist. You can also export the cookie yourself as a Netscape-formatted text file and paste its contents into the text field under Settings, then press Validate Cookie File. A cookie counts as valid if yt-dlp can reach your private Liked Videos playlist.

Three warnings come with this power, all stated plainly in the official settings docs. First, using cookies can have unintended consequences — multiple users have reported that their account got flagged, and cookies can expire within a few hours. Second, cookie data can be used to take over your account, so treat it with utmost care, as you would any other password or credential. Third, there is only one cookie per TubeArchivist instance, and it is shared between all users — so if you later add family accounts, everyone downloads through your session.

How Do I Tubearchivist Subscribe to a Channel?

Subscribing to a channel downloads new videos as they come out — that is the set-and-forget arc. Click the Rescan Subscriptions icon and TubeArchivist starts a background task that checks your subscribed channels and playlists for new videos; for every video found it skips anything already downloaded or on your ignored list, and everything else goes into the download queue. The tubearchivist subscribe habit becomes fully automatic with two settings: enable Auto Start so subscription downloads jump ahead of one-off videos you added manually, and schedule the recurring tasks so rescan and download runs happen on a cron rhythm. The scheduler deliberately caps frequency at once per hour to avoid throttling.

Do not confuse subscribing with a full archival — the official FAQ draws the line explicitly. Subscribing to a channel is for downloading new videos as they come out; downloading a complete channel backlog is a separate action, done by adding the channel to the download queue with the form or the browser extension. Also tune your page sizes: yt-dlp analyzes pages of 50 videos by default, which is also the recommended value, and you can set per-type sizes for regular videos, Shorts, and streams — or set one to 0 to disable that type entirely.

How Do I Search Subtitles and Comments in My Archive?

This is the payoff that makes TubeArchivist more than a download folder. Start any search with the keyword full: to run a full-text search across your indexed subtitles, and the results show you the matching segments — clicking one jumps the video player straight to that timestamp. That only works if you enabled subtitle download and indexing on the settings page, which is the single most common reason the full: search returns nothing on a fresh install.

Comments are indexed too, with a configurable depth: the application settings take a max-comments,max-parents,max-replies,max-replies-per-thread value (the documented example is 1000,all,all,50,2), and TubeArchivist downloads comments during post processing after the download queue finishes. The official answer to "why Elasticsearch" is exactly this: full-text indexing and searching over your subtitles and comments. Everyday searches are forgiving as well — fuzzy matching is on by default and catches typos of one or two letters, multi-word queries use an AND operator (full: searches use OR), and keyword searches return 30 results per query.

How Do I Enable TubeArchivist SponsorBlock?

TubeArchivist SponsorBlock support skips sponsored segments using timestamps from the community SponsorBlock project. It lives in Settings, then Application, then the Integrations section — and every third-party integration in TubeArchivist is always opt in, so nothing phones home until you turn it on. You can also tune it per channel: the Channel About page lets you enable or disable SponsorBlock for individual channels, overriding the global setting. The practical pattern is to enable it globally and disable it on channels whose sponsor reads you actually enjoy, or vice versa.

How Do I Hand My Archive to TubeArchivist Jellyfin or Plex?

TubeArchivist is deliberately its own media server — the official FAQ says that is where the project's focus and effort goes — but you have full freedom to use your media as you wish, and there are official integration paths for the big two. For Jellyfin, install the TubeArchivist metadata plugin: add the repository https://github.com/tubearchivist/tubearchivist-jf-plugin/raw/master/manifest.json under Dashboard, then Plugins, then Repositories, install TubeArchivistMetadata from the catalog, restart Jellyfin, and point a media library at your TubeArchivist media folder. For Plex there is a scanner-and-agent combination at tubearchivist/tubearchivist-plex. If your media library is already running, our Jellyfin beginner guide walks through library setup from scratch.

The file naming makes these integrations reliable: every video lands at channel-id/video-id.mp4, and those values are guaranteed static, unique, and compatible with every filesystem. Two more official integrations deserve a mention: the Tube Archivist Companion browser extension for Firefox and Chrome (the same extension you used for the cookies step) adds videos straight to your download queue from YouTube pages, and Google Cast support exists but requires DISABLE_STATIC_AUTH plus an HTTPS reverse proxy in front of your instance.

Do I Need to Keep Updating yt-dlp?

YouTube changes constantly, and yt-dlp is the component that keeps up. TubeArchivist can automatically install the latest yt-dlp on container start — set the TA_AUTO_UPDATE_YTDLP environment variable to release or nightly depending on which track you want. But read the caution banner first: future versions of yt-dlp may not be compatible with your current TubeArchivist version, and subtle changes in yt-dlp might lead to unexpected, incomplete, or wrong data getting indexed.

The advanced docs are blunter: updating yt-dlp manually is very likely going to break things, and you should only do it if you know how to debug the project yourself. The safe posture for beginners is to pin the bundled yt-dlp, update TubeArchivist itself on release days, and only reach for TA_AUTO_UPDATE_YTDLP when downloads start failing across the board. Worth knowing: version 0.6.0 also ships a Deno runtime and a forked bgutil-ytdlp-pot-provider plugin so yt-dlp can handle YouTube's PO-token challenges, with the provider URL configurable in Settings under Application.

Can My Family Use It Too? Users and Roles

TubeArchivist is mostly a single-user application today. You can create multiple users with different names and passwords, but they will all share the same videos and channels — there is no per-user library isolation. What you do get is a small role ladder. The first account, created from TA_USERNAME and TA_PASSWORD, is a superuser with access to the /admin/ interface. Granting a user the Is Staff permission lets them modify the download queue, delete items, and change configuration settings.

The bottom rung is the read-only user: remove both the Is Staff and Superuser permissions and the account can browse and watch but cannot add to the download queue or delete anything. The docs are candid that this mode is minimally tested and mostly meant as a kids mode — it will most likely not hold against a sophisticated attacker, so treat it as convenience, not security. If you ever lock yourself out, the password reset runs from the command line: docker compose exec -it tubearchivist python manage.py ta_change_password username newpassword.

TubeArchivist vs MeTube: Which One Do I Want?

This is the most common comparison beginners ask about, and the answer is a clean split. MeTube beginner guide covers the other product: MeTube (github.com/alexta69/metube) is a simple web interface for yt-dlp in a single Docker container — you paste a link, pick a format and quality, and the file lands on your server. It has no login built in (authentication is expected at the reverse proxy), no media-server interface, and no search index. Do not confuse it with yashoncode/metube, an unrelated Android YouTube client that happens to share the name.

The one-line rule: MeTube is "just download files," TubeArchivist is "build your own searchable private YouTube." Choose the weight that matches the job.

What Changed in TubeArchivist 0.6.0?

Version 0.6.0, tagged October 25, 2026, is a breaking release — older guides written before it are now partially wrong, which is one more reason this tubearchivist tutorial exists. The headline changes improve security: TubeArchivist now runs under a dedicated, non-root user, so your compose file needs user: "1000:1000" on the tubearchivist service, and the bundled nginx server is gone — all media and artwork are served directly by the application.

7 Beginner Mistakes That Break a Fresh TubeArchivist Setup

Is There a TubeArchivist Mobile App?

There is no official TubeArchivist mobile app and no desktop app — verified across the docs, the GitHub README, and a dedicated search, which surfaces only the unrelated commercial TubeArchiver. What you do get is the responsive web UI, which works fine from any phone or tablet browser, and the Tube Archivist Companion browser extension for Firefox and Chrome for one-click archiving. That is the complete official client story: web UI plus companion extension.

Sources

• TubeArchivist GitHub repository (github.com/tubearchivist/tubearchivist) — stars, forks, license, releases, default branch
• TubeArchivist v0.6.0 release notes (github.com/tubearchivist/tubearchivist/releases/tag/v0.6.0) — breaking changes, migration steps, Elasticsearch 9.5.5
• TubeArchivist docker-compose.yml (raw.githubusercontent.com/tubearchivist/tubearchivist/develop/docker-compose.yml) — three-container stack, images, ports, volumes, ES heap settings
• TubeArchivist installation docs (docs.tubearchivist.com/installation/docker-compose/) — system requirements, vm.max_map_count, bind-mount ownership
• TubeArchivist environment variables docs (docs.tubearchivist.com/installation/env-vars/) — TA_HOST, TA_USERNAME, TA_PASSWORD, TA_PORT, REDIS_CON, ES_URL, ELASTIC_PASSWORD, TA_AUTO_UPDATE_YTDLP
• TubeArchivist application settings docs (docs.tubearchivist.com/settings/application/) — cookie import flow, subtitle indexing, comments config, SponsorBlock, integrations
• TubeArchivist FAQ (docs.tubearchivist.com/faq/) — bot detection, Jellyfin/Plex integrations, file naming, why Elasticsearch
• TubeArchivist users docs (docs.tubearchivist.com/users/) — first-user superuser, Is Staff, read-only kids mode, password reset command
• TubeArchivist channels docs (docs.tubearchivist.com/channels/) — subscriptions, rescan, SponsorBlock per-channel override
• TubeArchivist downloads docs (docs.tubearchivist.com/downloads/) — rescan subscriptions background task, download queue
• TubeArchivist scheduling docs (docs.tubearchivist.com/settings/scheduling/) — cron tasks, once-per-hour limit
• TubeArchivist search docs (docs.tubearchivist.com/search/) — full: prefix, fuzzy matching, timestamp jump
• TubeArchivist advanced docs (docs.tubearchivist.com/advanced/) — yt-dlp update warnings
• XDA Developers — TubeArchivist plus Jellyfin walkthrough (xda-developers.com) — install-and-pair pipeline framing
• Railway TubeArchivist deploy guide (railway.com/deploy/tubearchivist-your-own-youtube-archive--tubearchivist) — community throwaway-account advice
• MeTube GitHub repository (github.com/alexta69/metube) — web UI for yt-dlp, single container, port 8081

Frequently Asked Questions

How much RAM does TubeArchivist need?

Around 2 GB of available memory for a small testing setup and around 4 GB for a mid-to-large installation, per the official installation docs. Elasticsearch is the hungry one — it takes a 1 GB heap by default — and a big subtitle/comment index will use more, so watch memory as your archive grows.

Why do my downloads fail on a VPS?

Datacenter IPs and VPN exit IPs trip YouTube's bot detection more often. You will see "Sign in to confirm you're not a bot," HTTP 403 errors, or speeds dropping to a few KB/s. Import a YouTube cookie via the Companion extension, and consider the community advice to use a separate Google account rather than your main one.

Does TubeArchivist work on a Raspberry Pi?

Mostly, with one caveat. The main app and Redis containers are multi-architecture, but the bundled bbilly1/tubearchivist-es image is amd64-only, so on ARM64 you should use the official Elasticsearch 9.5.5 image instead. The developers note ARM64 builds are essentially untested, so expect to do some troubleshooting.

Can I archive a whole channel, not just new videos?

Yes — subscribing and full archival are two different actions. Subscribing downloads new videos as they come out; to archive a complete channel backlog, add the channel to the download queue with the form or the browser extension. That is the verbatim distinction from the official FAQ.

What happens to my archive when TubeArchivist updates?

Minor updates are routine, but breaking releases like 0.6.0 need the migration guide: the non-root user, the removed nginx server, and the renamed TA_PORT variable all change your compose file. Your downloaded videos and the Elasticsearch index survive updates — the migration is about the stack configuration, not your data.