🔗 ParseHub

社交媒体聚合解析器

轻量, 异步, 开箱即用的社交媒体解析与媒体下载库, 支持 17+ 平台

简体中文 | English

✨ 特性

🌍 广泛的平台支持 — 覆盖国内外 17+ 主流社交媒体平台
🧹 链接清理 — 自动提取分享文案中的链接，并清除可移除的跟踪参数
🎬 多媒体解析 — 支持视频, 图文, 动图, 实况照片和富文本文章
📦 同步 / 异步 API — 同时提供 async/await 与 *_sync 调用方式
🐚 CLI 支持 — 命令行原生支持，轻量开箱即用
🤖 Telegram Bot — 基于本项目的 Bot 已上线 → @ParseHuBot

🌐 支持平台

平台	视频	图文	其他
Twitter / X	✅	✅	📝 文章
Instagram	✅	✅
YouTube	✅		🎵 音乐
Facebook	✅
Threads	✅	✅
Bilibili	✅		📝 动态
抖音	✅	✅	☀️日常
TikTok	✅	✅
微博	✅	✅
小红书	✅	✅
贴吧	✅	✅
微信公众号		✅
快手	✅	✅
酷安		✅
皮皮虾	✅	✅
最右	✅	✅
小黑盒	✅	✅
Snapchat	✅
知乎	✅	✅	🐶 问答, 专栏, 圈子, 日报
豆瓣	✅	✅	👥 小组话题

📦 安装

CLI 安装

uv tool install "parsehub[cli]"
ph -v

Python 库安装

# uv
uv add parsehub

# 需要完整 CLI 能力时，可安装 `cli` 扩展
uv add "parsehub[cli]"

🚀 快速开始

CLI

解析链接或分享文案

parsehub "https://example.com/post/1"

# 短命令等价写法
ph "https://example.com/post/1"

下载媒体

ph d "https://example.com/post/1"

常用命令

命令	说明
`ph ls`	查看支持的平台
`ph set proxy <platform> <proxy>`	设置解析代理和下载代理
`ph set proxy <platform> <proxy> --for download`	只设置下载代理
`ph set cookie <platform>`	保存平台 Cookie
`ph set list`	查看配置列表
`ph set show <platform>`	查看平台配置

配置会自动按平台应用到后续解析和下载; 临时覆盖时仍可直接传参数:

ph "https://example.com/post/1" --proxy http://127.0.0.1:7890
ph d "https://example.com/post/1" --parse-proxy http://127.0.0.1:7890 --cookie "key=value"

Python API

同步解析

from parsehub import ParseHub

ph = ParseHub()
result = ph.parse_sync("https://www.xiaoheihe.cn/app/bbs/link/174972336")
print(result)

dr = result.download_sync()
print(dr)

异步解析

import asyncio
from parsehub import ParseHub


async def main():
    ph = ParseHub()
    result = await ph.parse("https://tieba.baidu.com/p/9939510114")
    print(result)

    dr = await result.download()
    print(dr)


asyncio.run(main())

下载媒体

from parsehub import ParseHub

ph = ParseHub()
result = ph.download_sync("https://www.xiaoheihe.cn/app/bbs/link/174972336")
print(result)

🔑 高级用法

需要登录态的平台可传 Cookie, 解析入口使用 cookie / proxy, 下载入口使用 parse_cookie / parse_proxy 作为解析阶段参数

当前支持 Cookie 的平台:

Twitter / X
Instagram
Threads
YouTube
Bilibili
抖音
TikTok
快手
小红书
知乎
豆瓣

from parsehub import ParseHub

ph = ParseHub()
result = ph.parse_sync(
    "https://example.com",
    cookie="key1=value1; key2=value2",
    proxy="http://127.0.0.1:7890",
)

Cookie 支持多种格式:

# Cookie header 字符串
ph.parse_sync("https://example.com", cookie="key1=value1; key2=value2")

# JSON 字符串
ph.parse_sync("https://example.com", cookie='{"key1": "value1", "key2": "value2"}')

# 字典
ph.parse_sync("https://example.com", cookie={"key1": "value1", "key2": "value2"})

下载进度回调

from parsehub import ParseHub
from parsehub.types import ProgressUnit


class ProgressTracker:
    async def __call__(self, current: int, total: int, unit: ProgressUnit, *args, task_name: str = "", **kwargs):
        print(f"[{task_name}] {current}/{total} ({unit})")


result = ParseHub().download_sync(
    "https://example.com",
    path="./downloads",
    callback=ProgressTracker(),
    callback_args=("extra_arg",),
    callback_kwargs={"task_name": "demo"},
)

unit 值:

bytes: 单文件下载时的字节进度
count: 多文件下载时的文件数量进度

保存 metadata.json

from parsehub import ParseHub

result = ParseHub().download_sync(
    "https://example.com",
    path="./downloads",
    save_metadata=True,
)

print(result.output_dir / "metadata.json")

全局配置

from pathlib import Path
from parsehub.config import GlobalConfig

GlobalConfig.default_save_dir = Path("./downloads")

错误处理

from parsehub import ParseHub
from parsehub.errors import ParseError, UnknownPlatform

try:
    result = ParseHub().parse_sync("https://example.com")
except UnknownPlatform:
    print("暂不支持该平台")
except ParseError as exc:
    print(f"解析失败: {exc}")

启用日志

from loguru import logger

logger.enable('parsehub')

🤝 参与贡献

欢迎提交 Pull Request 或 Issue!

Bug 反馈请附上相关 URL 和日志信息

开发规范

提交代码前请至少执行:

ruff format && ruff check --fix && uv run mypy
uv run pytest

🤝 参考项目

📜 开源协议

本项目基于 MIT License 开源

如果这个项目对你有帮助，欢迎点个 ⭐ Star!

Metadata

Release files for parsehub 2.2.4

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for parsehub 2.2.4
File	Size	Uploaded
parsehub-2.2.4.tar.gz	121.9 kB	Sep 19, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for parsehub 2.2.4
File	Interpreter	ABI	Platform	Reset
parsehub-2.2.4-py3-none-any.whl 134.6 kB Sep 19, 2026	Python 3	none	any	Details

Total release size: 256.5 kB

Release files / parsehub-2.2.4.tar.gz

Download URL	parsehub-2.2.4.tar.gz
Size	121.9 kB
Tags	Source
SHA-256 checksum How to use checksums	`95ed12f8785d86a117537fb7101607e6a1192805be01b051cf1cba8c4693228f`
BLAKE2b-256 checksum How to use checksums	`8909199bb409054b0436442f131ff501a9c1b268834b9942cbc61d2b31a67442`
Upload date	Sep 19, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`twine/7.0.0 CPython/3.13.14`

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Identity

Publishing platform: GitHub Actions
Publishing repository: github.com/z-mio/ParseHub
Publishing commit: github.com/z-mio/ParseHub/tree/5cff7e8d9e14fa464599dc9a5e6c966ec5526c3e

Workflow

Publishing configuration: github.com/z-mio/ParseHub/blob/5cff7e8d9e14fa464599dc9a5e6c966ec5526c3e/.github/workflows/python-publish.yml
Publishing logs: github.com/z-mio/ParseHub/actions/runs/35416771036/attempts/1

Artifact

Subject: parsehub-2.2.4.tar.gz
SHA-256 checksum: 95ed12f8785d86a117537fb7101607e6a1192805be01b051cf1cba8c4693228f Verifying attestations

Release files / parsehub-2.2.4-py3-none-any.whl

Download URL	parsehub-2.2.4-py3-none-any.whl
Size	134.6 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`0c4c541edb714d877be59a47f65eb18d50fa1ac820870078f3342de8cf395bfa`
BLAKE2b-256 checksum How to use checksums	`c49853e45092597128d6f49b2a5917794c4ece68d3a0da27a86bc95b17c02b53`
Upload date	Sep 19, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`twine/7.0.0 CPython/3.13.14`

Provenance

Identity

Publishing platform: GitHub Actions
Publishing repository: github.com/z-mio/ParseHub
Publishing commit: github.com/z-mio/ParseHub/tree/5cff7e8d9e14fa464599dc9a5e6c966ec5526c3e

Workflow

Publishing configuration: github.com/z-mio/ParseHub/blob/5cff7e8d9e14fa464599dc9a5e6c966ec5526c3e/.github/workflows/python-publish.yml
Publishing logs: github.com/z-mio/ParseHub/actions/runs/35416771036/attempts/1

Artifact

Subject: parsehub-2.2.4-py3-none-any.whl
SHA-256 checksum: 0c4c541edb714d877be59a47f65eb18d50fa1ac820870078f3342de8cf395bfa Verifying attestations