Official repository: <https://github.com/Brainicism/bgutil-ytdlp-pot-provider>
# BgUtils POT Provider
> [!CAUTION]
> Providing a PO token does not guarantee bypassing 403 errors or bot checks, but it _may_ help your traffic seem more legitimate.
[](https://hub.docker.com/r/brainicism/bgutil-ytdlp-pot-provider)
[](https://github.com/Brainicism/bgutil-ytdlp-pot-provider/releases)
[](https://pypi.org/project/bgutil-ytdlp-pot-provider/)
[](https://github.com/Brainicism/bgutil-ytdlp-pot-provider/actions/workflows/test.yml)
A proof-of-origin token (POT) provider yt-dlp. We use [LuanRT's Botguard interfacing library](https://github.com/LuanRT/BgUtils) to generate the token.
This is used to bypass the 'Sign in to confirm you're not a bot' message when invoking yt-dlp from an IP address flagged by YouTube. See _[PO Token Guide](https://github.com/yt-dlp/yt-dlp/wiki/PO-Token-Guide)_ for more details.
The provider comes in two parts:
1. **Provider**: Two options -
- (a) An HTTP server that generates the POT, and has interfaces for the plugin to retrieve data from (easy setup + docker image provided)
- (b) A POT generation script, and has command line options for the plugin to invoke (needs to transpile the script)
2. **Provider plugin**: uses POT plugin framework to retrieve data from the provider, allowing yt-dlp to simulate having passed the 'bot check'.
## Installation
### Base Requirements
1. Requires yt-dlp `2025.05.22` or above.
2. If using Docker image for option (a) for the provider, the Docker runtime is required.
Otherwise, Node.js (>= 18) is required. You will also need git to clone the repository.
### 1. Set up the provider
There are two options for the provider, an always running POT generation HTTP server, and a POT generation script invoked when needed. The HTTP server option is simpler, faster, and comes with a prebuilt Docker image. **You only need to choose one option.**
#### (a) HTTP Server Option
The provider is a Node.js HTTP server. You have two options for running it: as a prebuilt docker image, or manually as a node application.
**Docker:**
```shell
docker run --name bgutil-provider -d -p 4416:4416 --init brainicism/bgutil-ytdlp-pot-provider
```
**Native:**
```shell
# Replace 1.2.1 with the latest version or the one that matches the plugin
git clone --single-branch --branch 1.2.1 https://github.com/Brainicism/bgutil-ytdlp-pot-provider.git
cd bgutil-ytdlp-pot-provider/server/
npm install
npx tsc
node build/main.js
```
**Server Command Line Options**
- `-p, --port <PORT>`: The port on which the server listens.
#### (b) Generation Script Option
> [!IMPORTANT]
> This method is not recommended for high concurrency usage. Every yt-dlp call incurs the overhead of spawning a new node process to run the script. This method also handles cache concurrency poorly.
1. Transpile the generation script to Javascript:
```shell
# If you want to use this method without specifying `script_path` extractor argument
# on each yt-dlp invocation, clone/extract the source code into your home directory.
# Replace `~` with `%USERPROFILE%` if using Windows
cd ~
# Replace 1.2.1 with the latest version or the one that matches the plugin
git clone --single-branch --branch 1.2.1 https://github.com/Brainicism/bgutil-ytdlp-pot-provider.git
cd bgutil-ytdlp-pot-provider/server/
npm install
npx tsc
```
2. Make sure `node` is available in your `PATH`.
### 2. Install the plugin
#### PyPI:
If yt-dlp is installed through `pip` or `pipx`, you can install the plugin with the following:
```shell
python3 -m pip install -U bgutil-ytdlp-pot-provider
```
#### Manual:
1. Download the latest release zip from [releases](https://github.com/Brainicism/bgutil-ytdlp-pot-provider/releases).
2. Install it by placing the zip into one of the [plugin folders](https://github.com/yt-dlp/yt-dlp#installing-plugins).
## Usage
If using option (a) HTTP Server for the provider, and the default IP/port number, you can use yt-dlp like normal 🙂.
If you want to change the port number used by the provider server, use the `--port` option.
```shell
node build/main.js --port 8080
```
If changing the port or IP used for the provider server, pass it to yt-dlp via `base_url`
```shell
--extractor-args "youtubepot-bgutilhttp:base_url=http://127.0.0.1:8080"
```
If the tokens are no longer working, passing `disable_innertube=1` to yt-dlp restores the legacy behaviour and _might_ help
```shell
--extractor-args "youtubepot-bgutilhttp:base_url=http://127.0.0.1:8080;disable_innertube=1"
```
Note that when you pass multiple extractor arguments to one provider or extractor, they are to be separated by semicolons(`;`) as shown above. Multiple `--extractor-args` will **NOT** work for the same provier/extractor.
---
If using option (b) script for the provider, with the default script location in your home directory (i.e: `~/bgutil-ytdlp-pot-provider` or `%USERPROFILE%\bgutil-ytdlp-pot-provider`), you can also use yt-dlp like normal.
If you installed the script in a different location, pass it as the extractor argument `script_path` to `youtube-bgutilscript` for each yt-dlp call.
```shell
--extractor-args "youtubepot-bgutilscript:script_path=/path/to/bgutil-ytdlp-pot-provider/server/build/generate_once.js"
```
---
We use a cache internally for all generated tokens when option (b) script is used. You can change the TTL (time to live) for the token cache with the environment variable `TOKEN_TTL` (in hours, defaults to 6). It's currently impossible to use different TTLs for different token contexts (can be `gvs`, `player`, or `subs`, see [Technical Details](https://github.com/yt-dlp/yt-dlp/wiki/PO-Token-Guide#technical-details) from the PO Token Guide).
That is, when using the script method, you can pass a `TOKEN_TTL` to yt-dlp to use a custom TTL for PO Tokens.
---
If both methods are available for use, the option (a) HTTP server method will be prioritized.
### Verification
To check if the plugin was installed correctly, you should see the `bgutil` providers in yt-dlp's verbose output: `yt-dlp -v YOUTUBE_URL`.
```
[debug] [youtube] [pot] PO Token Providers: bgutil:http-1.2.1 (external), bgutil:script-1.2.1 (external)
```
Raw data
{
"_id": null,
"home_page": null,
"name": "bgutil-ytdlp-pot-provider",
"maintainer": "grqz",
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": "Brainicism <brainicism@gmail.com>",
"keywords": "yt-dlp, yt-dlp-plugin, yt-dlp-pot-provider",
"author": null,
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/a7/3f/62fc3c3668a0518cc6a0dab159362bf2c213c0baf7631d15899a98b83176/bgutil_ytdlp_pot_provider-1.2.1.tar.gz",
"platform": null,
"description": "Official repository: <https://github.com/Brainicism/bgutil-ytdlp-pot-provider>\n\n# BgUtils POT Provider\n\n> [!CAUTION]\n> Providing a PO token does not guarantee bypassing 403 errors or bot checks, but it _may_ help your traffic seem more legitimate.\n\n[](https://hub.docker.com/r/brainicism/bgutil-ytdlp-pot-provider)\n[](https://github.com/Brainicism/bgutil-ytdlp-pot-provider/releases)\n[](https://pypi.org/project/bgutil-ytdlp-pot-provider/)\n[](https://github.com/Brainicism/bgutil-ytdlp-pot-provider/actions/workflows/test.yml)\n\nA proof-of-origin token (POT) provider yt-dlp. We use [LuanRT's Botguard interfacing library](https://github.com/LuanRT/BgUtils) to generate the token.\n\nThis is used to bypass the 'Sign in to confirm you're not a bot' message when invoking yt-dlp from an IP address flagged by YouTube. See _[PO Token Guide](https://github.com/yt-dlp/yt-dlp/wiki/PO-Token-Guide)_ for more details.\n\nThe provider comes in two parts:\n\n1. **Provider**: Two options -\n - (a) An HTTP server that generates the POT, and has interfaces for the plugin to retrieve data from (easy setup + docker image provided)\n - (b) A POT generation script, and has command line options for the plugin to invoke (needs to transpile the script)\n2. **Provider plugin**: uses POT plugin framework to retrieve data from the provider, allowing yt-dlp to simulate having passed the 'bot check'.\n\n## Installation\n\n### Base Requirements\n\n1. Requires yt-dlp `2025.05.22` or above.\n\n2. If using Docker image for option (a) for the provider, the Docker runtime is required. \n Otherwise, Node.js (>= 18) is required. You will also need git to clone the repository.\n\n### 1. Set up the provider\n\nThere are two options for the provider, an always running POT generation HTTP server, and a POT generation script invoked when needed. The HTTP server option is simpler, faster, and comes with a prebuilt Docker image. **You only need to choose one option.**\n\n#### (a) HTTP Server Option\n\nThe provider is a Node.js HTTP server. You have two options for running it: as a prebuilt docker image, or manually as a node application.\n\n**Docker:**\n\n```shell\ndocker run --name bgutil-provider -d -p 4416:4416 --init brainicism/bgutil-ytdlp-pot-provider\n```\n\n**Native:**\n\n```shell\n# Replace 1.2.1 with the latest version or the one that matches the plugin\ngit clone --single-branch --branch 1.2.1 https://github.com/Brainicism/bgutil-ytdlp-pot-provider.git\ncd bgutil-ytdlp-pot-provider/server/\nnpm install\nnpx tsc\nnode build/main.js\n```\n\n**Server Command Line Options**\n\n- `-p, --port <PORT>`: The port on which the server listens.\n\n#### (b) Generation Script Option\n\n> [!IMPORTANT]\n> This method is not recommended for high concurrency usage. Every yt-dlp call incurs the overhead of spawning a new node process to run the script. This method also handles cache concurrency poorly.\n\n1. Transpile the generation script to Javascript:\n\n```shell\n# If you want to use this method without specifying `script_path` extractor argument\n# on each yt-dlp invocation, clone/extract the source code into your home directory.\n# Replace `~` with `%USERPROFILE%` if using Windows\ncd ~\n# Replace 1.2.1 with the latest version or the one that matches the plugin\ngit clone --single-branch --branch 1.2.1 https://github.com/Brainicism/bgutil-ytdlp-pot-provider.git\ncd bgutil-ytdlp-pot-provider/server/\nnpm install\nnpx tsc\n```\n\n2. Make sure `node` is available in your `PATH`.\n\n### 2. Install the plugin\n\n#### PyPI:\n\nIf yt-dlp is installed through `pip` or `pipx`, you can install the plugin with the following:\n\n```shell\npython3 -m pip install -U bgutil-ytdlp-pot-provider\n```\n\n#### Manual:\n\n1. Download the latest release zip from [releases](https://github.com/Brainicism/bgutil-ytdlp-pot-provider/releases).\n2. Install it by placing the zip into one of the [plugin folders](https://github.com/yt-dlp/yt-dlp#installing-plugins).\n\n## Usage\n\nIf using option (a) HTTP Server for the provider, and the default IP/port number, you can use yt-dlp like normal \ud83d\ude42.\n\nIf you want to change the port number used by the provider server, use the `--port` option.\n\n```shell\nnode build/main.js --port 8080\n```\n\nIf changing the port or IP used for the provider server, pass it to yt-dlp via `base_url`\n\n```shell\n--extractor-args \"youtubepot-bgutilhttp:base_url=http://127.0.0.1:8080\"\n```\n\nIf the tokens are no longer working, passing `disable_innertube=1` to yt-dlp restores the legacy behaviour and _might_ help\n\n```shell\n--extractor-args \"youtubepot-bgutilhttp:base_url=http://127.0.0.1:8080;disable_innertube=1\"\n```\n\nNote that when you pass multiple extractor arguments to one provider or extractor, they are to be separated by semicolons(`;`) as shown above. Multiple `--extractor-args` will **NOT** work for the same provier/extractor.\n\n---\n\nIf using option (b) script for the provider, with the default script location in your home directory (i.e: `~/bgutil-ytdlp-pot-provider` or `%USERPROFILE%\\bgutil-ytdlp-pot-provider`), you can also use yt-dlp like normal.\n\nIf you installed the script in a different location, pass it as the extractor argument `script_path` to `youtube-bgutilscript` for each yt-dlp call.\n\n```shell\n--extractor-args \"youtubepot-bgutilscript:script_path=/path/to/bgutil-ytdlp-pot-provider/server/build/generate_once.js\"\n```\n\n---\n\nWe use a cache internally for all generated tokens when option (b) script is used. You can change the TTL (time to live) for the token cache with the environment variable `TOKEN_TTL` (in hours, defaults to 6). It's currently impossible to use different TTLs for different token contexts (can be `gvs`, `player`, or `subs`, see [Technical Details](https://github.com/yt-dlp/yt-dlp/wiki/PO-Token-Guide#technical-details) from the PO Token Guide). \nThat is, when using the script method, you can pass a `TOKEN_TTL` to yt-dlp to use a custom TTL for PO Tokens.\n\n---\n\nIf both methods are available for use, the option (a) HTTP server method will be prioritized.\n\n### Verification\n\nTo check if the plugin was installed correctly, you should see the `bgutil` providers in yt-dlp's verbose output: `yt-dlp -v YOUTUBE_URL`.\n\n```\n[debug] [youtube] [pot] PO Token Providers: bgutil:http-1.2.1 (external), bgutil:script-1.2.1 (external)\n```\n",
"bugtrack_url": null,
"license": null,
"summary": null,
"version": "1.2.1",
"project_urls": null,
"split_keywords": [
"yt-dlp",
" yt-dlp-plugin",
" yt-dlp-pot-provider"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "6f37c66e32bdb34b84581b8a794bdc86775b1161208f915f103e39bd1ad665d3",
"md5": "97ece0e5a053df07667e0b58b865679b",
"sha256": "ddf9fee9857fb64c7fdfb4db96db81ca5864a6004fff5549a2043693776184ef"
},
"downloads": -1,
"filename": "bgutil_ytdlp_pot_provider-1.2.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "97ece0e5a053df07667e0b58b865679b",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 9473,
"upload_time": "2025-08-07T05:41:03",
"upload_time_iso_8601": "2025-08-07T05:41:03.959095Z",
"url": "https://files.pythonhosted.org/packages/6f/37/c66e32bdb34b84581b8a794bdc86775b1161208f915f103e39bd1ad665d3/bgutil_ytdlp_pot_provider-1.2.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "a73f62fc3c3668a0518cc6a0dab159362bf2c213c0baf7631d15899a98b83176",
"md5": "a7f55c371be0a817a4223b3d18b85385",
"sha256": "771173df631451046c982dcac27482cc89b300ce0aedc487043f80e45774b9f6"
},
"downloads": -1,
"filename": "bgutil_ytdlp_pot_provider-1.2.1.tar.gz",
"has_sig": false,
"md5_digest": "a7f55c371be0a817a4223b3d18b85385",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 8889,
"upload_time": "2025-08-07T05:41:05",
"upload_time_iso_8601": "2025-08-07T05:41:05.318148Z",
"url": "https://files.pythonhosted.org/packages/a7/3f/62fc3c3668a0518cc6a0dab159362bf2c213c0baf7631d15899a98b83176/bgutil_ytdlp_pot_provider-1.2.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-07 05:41:05",
"github": false,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"lcname": "bgutil-ytdlp-pot-provider"
}
JSON