取数这一步确实是省事的
不需要申请账号、不需要 API Key、不需要自建行情库：pip install yfinance 之后，行情、分红拆股、财务报表、期权链、基金持仓、筛选器都在同一个包里，返回的直接是 pandas DataFrame / Series。
yfinance · Python 金融数据获取库（非 Yahoo 官方产品）
yfinance 中文手册：数据取回来之后，先弄清它到底给了你什么
yfinance 让你用一行 yf.download("AAPL", period="1mo") 把 Yahoo Finance 的行情、分红拆股、财务报表与期权链接成 pandas 对象。但真正决定研究结论对不对的，不是「能不能取到」，而是取到的是不是你以为的那份数据：默认 auto_adjust=True 会让 Adj Close 列整列消失、单只股票也会返回两层 MultiIndex、分钟线受 60 天窗口限制、Yahoo 侧的价格本身可能存在 100 倍货币错位或漏做分红调整。本站把官方仓库固定到 commit 并用同一台机器实测两个版本，逐条给出返回结构、字段含义与失败边界。
项目来源
仓库页面显示约 25,465 Star、3,437 Fork、106 个 open issues；许可为 Apache-2.0。数字随社区变化，采集日期为 2026-10-09。
查看源码
What it solves
yfinance 解决什么问题，又留下哪些坑？
把它当成「免账号取金融数据」的入口是对的；把它当成「数据一定干净、一定能回测」的入口就会踩坑。
难的是「这份数据代表什么」
同一个 history() 调用，auto_adjust 取 True 还是 False 会得到列集合都不同的两张表（7 列 vs 8 列）；Close 在复权前后含义不同；A 股默认拿到的是复权价。这些差异不写进代码注释里，就会一路带到回测结论里。
Yahoo 侧的数据本身不完美
官方 price repair 文档自述「Only US market data appears perfect」，并列出漏做分红调整、漏做拆股调整、整行缺失、100 倍货币错位、重复分红、分红金额错误、除权日错位、资本利得重复计算等真实错误类型。
本站的定位：不重复官方 API 文档，而是把「返回结构的实测记录 + 字段语义 + 失败边界 + 审计模板」放在一起，让你在把数据交给策略之前，先能回答「这份数据能不能用」。
How it works
怎么用：五步拿到一份「知道自己是什么」的数据
下面五步都是可复制的，命令与参数取自官方源码签名；每步都标了「该确认什么」。
- 装环境并核对版本 官方建议用虚拟环境：
python -m venv .venv后pip install yfinance。装完先跑import yfinance; print(yfinance.__version__)——本站实测本机自带环境预装的是 0.2.58，而 PyPI 最新是 1.7.0，两代版本的能力面差别很大。 - 先取一次最小样本
yf.Ticker("AAPL").history(period="1mo")。本站实测返回 22 行 × 7 列，索引为Date、时区America/New_York、时间为00:00:00。先看清列名，再决定要不要调整auto_adjust。 - 决定复权口径 要真实成交价就用
auto_adjust=False（多出Adj Close列）；要做收益序列就用默认的auto_adjust=True，但要记住Adj Close列已经不存在了。两种口径不要在同一段代码里混用。 - 批量取数并处理列结构
yf.download(["AAPL","MSFT"], period="1mo")返回 2 层 MultiIndex（轴顺序是「字段 → 标的」），加group_by="ticker"可换成「标的 → 字段」。注意：只传一只股票也会是两层。 - 落盘前先跑审计 保存成 CSV/Parquet 之前，先跑一遍审计页的 13 项检查（空表、日期重复、日期连续性、OHLC 关系、负价格、极端跳点、复权事件一致性、时区、最新数据时间等），得到「可用于探索性分析 / 需人工复核 / 不建议直接回测」三态结论。
Route
该先读哪一页：按你的目标选一条阅读路线
每一页都对应一个具体的卡点，不是按 API 类名罗列。
| 你现在的目标 | 建议先看 | 这一页会给你什么 |
|---|---|---|
| 把包装上并确认版本对得上 | 安装与版本 | 安装命令、依赖解析实测、两代版本能力对照、同环境依赖冲突原文 |
| 搞清楚返回的 DataFrame 长什么样 | 取数结构 | history 与 download 的列/索引/MultiIndex 实测记录，以及 group_by、end 开区间、跨市场并集等细节 |
| 分清 Close 与 Adj Close | 复权语义 | utils.auto_adjust() 的源码级语义、auto_adjust 前后列集合变化、A 股复权价实测 |
| 分红拆股让序列对不上价格 | 分红与修复 | Dividends / Stock Splits / Capital Gains 三列语义、repair 的 8 类修复与假阳性边界 |
| 要读财务报表或期权链 | 财务与期权 | 报表行列数与 dtype 实测、列＝财年末日期的含义、option_chain 的 14 个字段与空 volume 处理 |
| 写了 A 股/港股代码却取不到数 | ticker 与市场 | 后缀规则、7 个标的实测对照、交易日历差异导致的 NaN 与 dtype 变化 |
| 数据拿到手，不确定能不能回测 | 数据审计与回测 | 13 项审计检查、三态结论、回测前七条红线 |
| 报错、空表、被限流 | 故障排查 | 9 类真实故障的现象/复现/原因/解决/不可解，含本站实测的报错原文 |
Setup and route
自己写 Python 取数，还是先用本机技能把问题问清楚？
两条路线的准备成本不一样，先按你的目标选。
装 Python 环境→pip 安装→选复权口径→审计后落盘
换来的是完全可控：列名、复权口径、缓存位置、重试策略、落盘格式都由你决定，报错信息也能拿到原文。代价是要自己维护环境，并自己承担「数据语义判断」这件事。
安装桌面端软件→用一句话提问
本机已核验的技能里，yahoo-finance-github 与 stock-price-checker 本身就是基于 yfinance 库实现的取数入口，fp-dcf 也把 yfinance 列为财务数据来源之一。但请注意：这是「技能调用 yfinance 库」，不是「yfinance 集成进了这套技能体系」，两者不要混同。
路线边界：yfinance 是独立的 Python 包，走 PyPI 安装；这套技能体系里不存在「安装 yfinance」这一路由。本站并列介绍的是两条独立路线：自己写取数代码，以及用本机已核验技能免部署地做研究。两条路线的数据口径与结果都需要你自己复核，也都不构成投资建议。
免部署 demo
本机技能路线怎么用：用户实测截图演示（2026-10-09）
以下为 2026-10-09 在本机 EasyClaw 上实拍的对话截图，用于对照「自建取数流程：装环境 + 选口径 + 写审计」的准备成本。截图演示的是本机技能路线，不是 yfinance 自身的运行结果；示例标的为 A 股，与本站举例的标的无对应关系。yfinance 与 EasyClaw 无已证实集成，截图仅供研究参考。
Who fits
yfinance 适合谁、不适合谁？
先确认边界，再决定投入。
适合你，如果…
你会写一点 Python、要做的是日线级别的研究（行情、财务报表、期权链、基金持仓），并且愿意在把数据交给策略之前做一次口径核对。学生做课程项目、研究者做原型验证、量化爱好者做组合分析，都在这个范围内。
不太适合，如果…
你需要分钟级高频数据（官方文档写明日内数据不能超过最近 60 天，且 30 分钟线是 15 分钟重采样而来）、需要实盘下单能力（库本身没有交易功能），或者需要数据源方提供 SLA 与准确率承诺。
用之前必须知道的三件事
①默认 auto_adjust=True，拿到的是复权价；②Yahoo 侧存在真实价格错误，repair=True 只能修 1 日线口径；③数据只允许 personal use，商用与再分发前请自己读 Yahoo Terms of Use。
Facts
项目事实速查：版本、依赖与许可各是什么？
下表的每一项都能指到官方仓库文件、PyPI 返回或本站实测记录；采集时间为 2026-10-09，数字会随项目进展变化。
| 项目 | 事实 | 来源 | 注意点 |
|---|---|---|---|
| 仓库 | ranaroussi/yfinance，默认分支 main | GitHub API（2026-10-09） | 本项目与 Yahoo 公司无隶属关系 |
| 最近版本 | PyPI 最新 1.7.0（2026-08-26 上传）；仓库内 version.py 同为 1.7.0 | PyPI JSON API + 仓库源码 | 历史累计 150 个版本，升级前先看 CHANGELOG |
| 社区规模 | 约 25,465 Star、3,437 Fork、106 个 open issues | GitHub API（2026-10-09） | 数字随社区变化，引用时请标采集日期 |
| Python 版本 | 仓库未声明 requires-python，PyPI 该字段亦为空；classifiers 仍列 3.6–3.13 | pyproject.toml / PyPI | 不要依赖 classifiers 判断可用性，以实际安装结果为准 |
| 许可 | 代码 Apache-2.0；数据受 Yahoo Terms of Use 约束 | LICENSE.txt + README | README 写明 intended for personal use only |
| 关键依赖 | curl_cffi>=0.15、pandas>=1.3.0、numpy>=1.16.5、peewee、websockets>=13.0；可选 repair extra 额外装 scipy + scikit-learn | pyproject.toml | 1.2.1 起因 CVE 强制 curl_cffi，1.4.0 起改为可选回退 requests |
| 本机实测版本 | 本机自带 Python 3.11.9 预装 0.2.58；独立 venv 装 1.7.0 | 本站实测（2026-10-09） | 两代版本能力面差异见安装页对照表 |
| 缓存位置 | platformdirs.user_cache_dir()/py-yfinance（Windows 为 %LOCALAPPDATA%\py-yfinance），存时区与 cookie | 源码 cache.py + 官方 caching 文档 | 可用 yf.set_tz_cache_location() 改位置 |
| 默认调试行为 | yf.config.debug.hide_exceptions 默认为 True（默认吞掉异常） | 源码 config.py + 官方 config 文档 | 排障时先把它设为 False，否则很多错误看不到 |
Limits
yfinance 不做什么：先记住四条边界
把这四条写进项目 README 的「已知限制」一节，比事后向人解释更省事。
| 你以为它能做 | 实际情况 | 官方依据 | 你该怎么做 |
|---|---|---|---|
| 提供实时、低延迟行情 | 官方定位是研究与教育用途；库不含延迟与稳定性承诺 | README 写明 intended for research and educational purposes | 实盘用交易所或券商级行情源，并自行完成合规确认 |
| 替你在券商下单、执行交易 | 库只做数据获取与整理，没有交易执行能力 | README 的组件清单里没有任何交易或下单模块 | 执行链路由你自己的交易系统承担，不要在数据层上强加执行语义 |
| 是 Yahoo 官方 API | 不是。它是第三方开源工具，读取 Yahoo 公开接口 | README 明确 not affiliated, endorsed, or vetted by Yahoo, Inc. | 对外文档里不要写成「Yahoo 官方接口」，避免误导与合规风险 |
| 保证数据一定准确 | 官方自述只有美股数据「看起来完美」，并列出了多类真实价格错误 | 官方 price repair 文档列出漏做分红调整、100 倍货币错位等错误类型 | 把审计当流程：取数后先跑检查，再决定能否用于分析 |
这四条不是免责套话，而是会直接影响选型的判断依据。例如「需不需要实时性」这一条，就决定了你是继续用它做研究，还是必须换成有 SLA 的商用数据源——这个判断不必等你写完策略才发现。
Reading path
读完这一页该去哪：按你的处境选下一页
本页给的是全局判断；真正的口径细节在分页里，按需进入即可。
| 你的处境 | 先确认什么 | 再看哪一页 |
|---|---|---|
| 刚装完，不知道从哪开始 | 先跑一次 history(period="5d")，把列名打印出来 | 取数结构 |
| 要算收益，但不确定用哪一列 | 先确认当前口径下有没有 Adj Close 列 | 复权语义 |
| 怀疑某天价格不对 | 把 Dividends 与 Stock Splits 和价格跳变对照 | 分红与修复 |
| 要读报表或期权链 | 先确认列是报告期还是公告日；期权只看当前快照 | 财务与期权 |
| 写了 A 股或港股代码取不到数 | 先确认后缀写法，再确认主机可达性 | ticker 与市场 |
| 数据拿到手，准备写策略 | 先跑一遍审计清单，拿到三态结论再动手 | 数据审计与回测 |
| 报错或一直返回空表 | 先打开异常可见性，再做环境对照 | 故障排查 |
一句话的使用方式：把本页当成索引，把分页当成口径手册。真正会改变你结论的，是每个分页里「实测记录」那一节给出的具体数字与列清单。
FAQ
yfinance 常见问题
下面的回答都指向可核验的官方文件或本站实测；与官方表述冲突时，以官方仓库与 docs 为准。
yfinance 是 Yahoo 官方 API 吗？
不是。官方 README 明确写着 yfinance not affiliated, endorsed, or vetted by Yahoo, Inc.，它是第三方开源工具，读取 Yahoo 公开接口；README 同时写明 the Yahoo! finance API is intended for personal use only。两者容易混淆，做合规判断时请以 README 与 Yahoo Terms of Use 原文为准。
yfinance 免费吗？有没有账号或 API Key？
库本身以 Apache-2.0 发布、不需要注册账号或 API Key。但要注意两点：①数据下载的权利受 Yahoo Terms of Use 约束，README 指定了 personal use only；②免费不等于稳定——请求会被 Yahoo 限流，命中时限流异常原文为 Too Many Requests. Rate limited. Try after a while.（YFRateLimitError）。
yfinance 能取 A 股和港股吗？
可以取数：本站实测 600519.SS、000001.SZ、688981.SS（沪/深/科创板）与 0700.HK 都能返回完整日线。需要注意两点：一是默认 auto_adjust=True，拿到的是复权后价格而不是当日真实成交价；二是交易日历与美股不同（实测同一 1 个月窗口，A 股 17 行、美股 22 行）。另外提醒：本机某个技能的说明里写「不支持 A 股与港股」，那是那个技能脚本的参数设计限制，不是 yfinance 库的限制，两者不要混为一谈。
取到的数据能直接拿去回测吗？
不能直接。本站数据审计页给出 13 项检查与三态结论，其中「不建议直接用于回测」最常见的三种情形是：①混用了 Close 与 Adj Close；②把财务报表按报告期当成当时可知信息（point-in-time 错误）；③用当前存续标的列表回测历史（幸存者偏差）。这三项都属于口径问题，不是代码 bug，也不会报错。
yfinance 能拿实时行情吗？
README 把这条边界写得很清楚：面向 research and educational purposes。库里有 WebSocket 流式接口（1.0 起提供），但本站没有实测实时性与延迟，也不建议把 yfinance 当作实盘行情的可靠性来源——本站不发布任何「实时」「低延迟」类结论，实盘场景请以交易所或券商级行情为准。
可以在本机技能路线里用 yfinance 取数吗？
要分清两件事：EasyClaw 里没有「安装 yfinance」这个技能路由，yfinance 项目与 EasyClaw 无已证实集成；但本机技能目录里确实有 3 个技能在直接调用 yfinance 库（yahoo-finance-github、stock-price-checker、fp-dcf），另有 quant-analyst 把 yfinance 注册为可测试数据源，本站实跑其自检脚本输出 [OK] yfinance reachable (AAPL quote fetched).。这两条是并列事实，详见对比页。