pydoll

n8n community node for pydoll via Python runner with Chrome pre-download

Package Information

Downloads: 5 weekly / 28 monthly
Latest Version: 0.1.4
Author: rexqin

Available Nodes

Pydoll icon
Pydoll
Run pydoll automation through Python runner

Documentation

n8n-nodes-pydoll

n8n community node package that runs pydoll with a Python runner strategy.

Features

  • Single node: Pydoll
  • executionMode supports:
    • per_item: process each item separately
    • batch: process all items in one Python call
  • Runner-aligned behavior:
    • Internal mode: install Python deps and pre-download Chrome at postinstall
    • External mode: provide custom n8nio/runners extension image in docker/runners
  • Credentials（凭证）：在 n8n 中创建类型 Pydoll，可填写 Cookie、HTTP/SOCKS 代理及代理账号密码；节点执行时会传给 Python runner，用于需要登录或走代理的页面抓取。

Install in n8n

Install from npm in your n8n environment:

npm install n8n-nodes-pydoll

若界面提示 The specified package could not be loaded，请先升级本包到 ≥ 0.1.3（旧版凭证文件名与 n8n 加载约定不一致）；仍失败时可清空 n8n 社区节点目录后重装（例如 Docker：rm -rf /home/node/.n8n/nodes，再于界面重新安装）。

Optional environment variables:

  • PYDOLL_PYTHON_BIN: set custom python executable path
  • PYDOLL_SKIP_POSTINSTALL=1: skip all postinstall logic
  • PYDOLL_SKIP_CHROME_DOWNLOAD=1: skip Chrome pre-download only
  • PYDOLL_RUNNER_PATH: override runner script path (debug/testing)

n8n Python runner alignment

Internal mode (local runner process)

Set:

N8N_RUNNERS_ENABLED=true
N8N_RUNNERS_MODE=internal
N8N_NATIVE_PYTHON_RUNNER=true

In this mode, package postinstall performs:

  • pip install ./python（依赖见 python/pyproject.toml）
  • python -m playwright install chrome

External mode (recommended production)

Set:

N8N_RUNNERS_ENABLED=true
N8N_RUNNERS_MODE=external
N8N_RUNNERS_AUTH_TOKEN=your-token

Use custom runners image to include pydoll and pre-downloaded Chrome:

docker build -f docker/runners/Dockerfile -t your-org/n8n-runners:pydoll .

scripts/postinstall.js automatically skips local install when N8N_RUNNERS_MODE=external.

Python runner design

Node code calls python/runner.py through lib/python-bridge.js using stdin/stdout JSON protocol.

Input payload example:

{
  "executionMode": "batch",
  "operation": "fetch_page",
  "waitMs": 1000,
  "items": [
    { "index": 0, "url": "https://example.com", "json": {} }
  ]
}

Output payload example:

{
  "items": [
    {
      "url": "https://example.com",
      "title": "Example Domain",
      "html": "<html>...</html>",
      "sourceIndex": 0
    }
  ]
}

Development

Python 依赖统一写在 python/pyproject.toml（PyPI 上包名为 pydoll-python，代码里仍是 import pydoll）。

检查依赖是否可解析（不写全局环境；优先 uv，否则用 pip >= 22.3 的 install --dry-run）：

just check-deps

未安装 just 时可用：brew install just，或手动执行 cd python && uv pip compile pyproject.toml -o .deps-compile-check.txt && rm -f .deps-compile-check.txt。

npm test

Publish to npm with GitHub Actions

Workflow file: .github/workflows/publish.yml

Trigger modes:

  • 手动 workflow_dispatch：运行前选择 patch 或 minor，workflow 会用 npm version 自动递增 package.json 再发布（不写 git tag、不推回仓库）。
  • Release：创建 GitHub Release 并发布时使用当前提交里的 package.json 版本，不会在 CI 里自动 bump。

Infisical

发布时通过 Infisical/secrets-action（OIDC）拉取密钥；identity-id / project-slug / env-slug / secret-path 见 .github/workflows/publish.yml（当前：project-nd-zj、dev、路径 /n8n-node-pydoll）。

  1. 在该路径下配置 npm 凭证（如 NODE_AUTH_TOKEN 或 NPM_TOKEN，与 setup-node / npm publish 一致即可）。
  2. Machine Identity OIDC 需允许本仓库 workflow（见 官方文档）。
  3. 凭证顺序：workflow 会先拉 Infisical 再执行 setup-node 写 .npmrc；若先 setup-node 再拉密钥，容易出现 npm publish 报 404（实为未带上 token，npm 常把无权限表现成 404）。

npm 403：要求 2FA 或 Granular Token（绕过发布 2FA）

若日志出现类似：

Two-factor authentication or granular access token with bypass 2fa enabled is required to publish packages

说明当前 token 不能在 CI 里完成发布，需在 npmjs.com 账户侧处理（任选其一）：

  1. 推荐（适合 CI）：创建 Granular Access Token（细粒度访问令牌），在创建向导里为需要发布的包勾选 Publish，并启用 Allow this token to bypass two-factor authentication (2FA) for automation（或界面上的同等「自动化绕过 2FA」选项）。把新 token 写入 Infisical 的 NODE_AUTH_TOKEN / NPM_TOKEN。旧版 Classic 的 Automation 类 token 通常也可用于无交互发布，但若账户策略已收紧，请改用 Granular。
  2. 或：在 npm 账户上启用并配置好符合 npm 要求的 2FA 后，仍须使用 带发布权限且允许自动化绕过 2FA 的 token，否则纯「只读/无绕过」token 在 Actions 里会一直 403。

参考：Access tokens、Two-factor authentication。

Recommended release process:

方式 A（手动发版 + 自动 bump）：Actions → 选本 workflow → Run workflow → 选 patch 或 minor → Run。

方式 B（发 Release）：先在仓库里把 package.json 版本改好并推送 / 打 tag → 创建 GitHub Release → workflow 按该版本发布。

Discussion