① 记录四个数
解释器路径 sys.executable、Python 版本、yf.__version__、pandas 版本。本站实测过「同机两版本共存」的情形，只记 pip list 是不够的，要记实际 yfinance.__file__。
yfinance 安装 · 两代版本（0.2.x / 1.x）能力鸿沟
yfinance 安装与版本：为什么同一份代码在两台机器上返回的表不一样
安装本身只有一行 pip install yfinance，真正容易出事的是装到哪一代。本站实测发现：本机自带 Python 环境里预装的是 0.2.58，而 PyPI 上最新是 1.7.0；官方 CHANGELOG 对 1.0 的说明是「No breaking changes」，但把 dir(yfinance) 打出来会看到 1.x 多出 config / Auth / Calendars / WebSocket / Market / Screener 等一整套模块。本页把「怎么装、怎么验证、两代差在哪、什么情况下装不上」逐条落到可复现的记录上。
PyPI 安装
确认版本与路径
两代能力对照
列结构断言
Install
怎么确认装的是哪一代：先装包再核对
三步都是可复制的；注意最后一定要打印版本与路径。
- 建虚拟环境 官方文档建议用虚拟环境：
python -m venv .venv，Windows 激活.venv\Scripts\activate。本站实测就是在一个--system-site-packages的 venv 里装 1.7.0 做对照的，没有改动共享环境。 - 安装
pip install yfinance。要固定版本就写pip install "yfinance==1.7.0"。不要用--no-deps跳过依赖，除非你明确知道自己在做什么。 - 验证 两条命令：
python -c "import yfinance,sys;print(yfinance.__version__, sys.executable)"，以及一次真实取数yf.Ticker("AAPL").history(period="5d")。只看 import 成功不算装好——本站实测部分接口会在网络层失败。
# 最小验证脚本（本机实测通过：Python 3.11.9 + yfinance 1.7.0）
import sys, yfinance as yf
print("python :", sys.version.split()[0])
print("yfinance:", yf.__version__)
print("path :", yf.__file__)
df = yf.Ticker("AAPL").history(period="5d")
print("shape :", df.shape, list(df.columns))
print("index :", df.index.name, df.index.tz)预期输出（本机实测）：版本行打印
1.7.0；shape 形如 (4, 5) 或 (5, 7)（取决于 actions 默认与交易日）；index 打印 Date America/New_York。若 yf.__file__ 指向的不是你激活的 venv，说明解释器选错了。Version gap
两代版本到底差什么：dir() 级别的对照表
下表左右两列都是本站实测输出（同一台机器、同一网络、同一份探针脚本），不是从文档抄的。
| 能力 | 0.2.58（本机自带环境实测） | 1.7.0（独立 venv 实测） | 对你的影响 |
|---|---|---|---|
全局配置 yf.config | 无 | 有（network.proxy / network.retries / debug / locale） | 旧版改代理只能靠已废弃的 yf.set_config(proxy=…)；新版还能开 hide_exceptions |
| 异常可见性 | 异常默认被吞，排障难 | 可用 yf.config.debug.hide_exceptions = False 打开 | 排查「为什么返回空表」时，这条差异经常就是答案 |
实时流 WebSocket / AsyncWebSocket | 无 | 有 | 旧版拿不到流式接口，只能轮询 |
登录 Auth | 无 | 有 | 涉及账号态能力的场景只有 1.x 可用 |
交易日历 Calendars | 无 | 有（含财报日历） | 1.0 起新增，用于查询日历事件 |
市场对象 Market / MarketRegion | 无 | 有 | 做市场层面的汇总需要 1.x |
筛选器 EquityQuery / FundQuery / ETFQuery / screen | 无（实测 dir(yf) 不含） | 有 | 想用 Yahoo 内置筛选条件必须升级 |
顶层模块 lookup / search / calendars / pricing_pb2 | 仅 YfData、shared 等内部模块可见 | 上述模块直接可见 | 版本差异不止在 API 表面，内部结构也换了 |
history() 返回列结构 | 实测与 1.7.0 完全一致 | 实测与 0.2.58 完全一致 | 列结构没有变，所以「换版本导致列错」多数是别的原因 |
download() 的 auto_adjust 默认值 | 已是 True（运行时打印变更提示） | True（同上） | 两代都会打印 YF.download() has changed argument auto_adjust default to True |
Pitfalls
安装与升级最容易踩的几件事
下表左列是现象、中列是本站核实到的原因、右列是处理方式。
| 现象 | 原因（已核实） | 处理方式 | 能否彻底避免 |
|---|---|---|---|
import yfinance 成功但 yf.config 报 AttributeError | 装到的是 1.0 之前的版本（本机实测 0.2.58 确实没有 config） | 先打印版本，再决定是升版本还是改用旧写法 | 能——版本是可查的 |
装完提示与 finrl 之类包不兼容 | finrl 0.3.8 声明 yfinance<0.3,>=0.2。本站 venv 安装时 pip 原文告警：finrl 0.3.8 requires yfinance<0.3,>=0.2, but you have yfinance 1.7.0 which is incompatible. | 用独立 venv 分开两个项目，不要在同一环境里硬升 | 能——分环境即可 |
与 websockets 版本冲突 | yfinance 1.7.0 要求 websockets>=13.0，而环境中其它包（如 alpaca-trade-api、prefect、streamlit）对上限有各自要求 | 在同一环境里装之前先 pip install --dry-run 看解析结果 | 部分——取决于同环境其它包 |
依赖 curl_cffi 装不上或版本不符 | 1.2.1 起因 CVE 强制 curl_cffi>=0.15；1.4.0 起改为可选并回退 requests；1.5.2 修了 curl_cffi>=0.16 的崩溃 | 按官方「不带 curl_cffi 安装」路径操作，或锁版本 | 能——官方给了替代路径 |
repair=True 报缺少模块 | repair 不是默认依赖，官方把它放在 extra 里（scipy + scikit-learn） | pip install "yfinance[repair]" | 能 |
| 同一个脚本在同事机器上结果不同 | 两台机器装的是不同大版本；本机实测本机自带环境为 0.2.58、独立 venv 为 1.7.0 | 把 sys.executable 与 yf.__version__ 一起打进日志 | 能——写进产物即可 |
| 装完 import 成功，但某个属性不存在 | 该属性属于 1.x 新增模块（如 config）；旧版本没有对应实现，既不是拼写错误也不是权限问题 | 先打印版本，再对照本页的两代能力对照表定位 | 能——版本决定能力面 |
| 官方文档里的示例在本机跑不通 | 文档站是 Sphinx autodoc 自动生成的，页面内容随源码变化；你读到的示例可能对应某个中间版本 | 以仓库 tag/commit 对应的源码为准，并在记录里写明版本 | 部分——需固定版本阅读 |
关于最后一条的补充：官方文档站（
ranaroussi.github.io/yfinance）由仓库的 doc/source 自动构建，因此「文档里有的」与「你装的那版有的」可能不是同一时刻的状态。本站的做法是把核验固定到具体 commit，并在每个结论旁标注它来自哪个版本。Evidence
本站实测了什么：可复现的记录
下表是本次核验用到的环境与结果，命令与原始 JSON 都留在研究目录里，不依赖记忆。
| 项 | 实测值 | 说明 |
|---|---|---|
| 操作系统 | Windows 10.0.26200 | 本机环境 |
| Python | 3.11.9（本机自带解释器） | 两代版本共用同一个解释器 |
| 实测版本 A | yfinance 0.2.58（预装于本机自带环境） | 直接 import 使用，未做任何安装动作 |
| 实测版本 B | yfinance 1.7.0（新建 --system-site-packages venv 安装） | 未改动共享环境；pip 解析全部命中已有依赖 |
| pandas / numpy | 2.2.3 / 2.4.6 | 两代版本共用 |
| curl_cffi | 0.15.0 | 满足 >=0.15 要求 |
| 探针项数 | 44 项（行情、批量、分红拆股、财务、期权、跨市场、故障路径） | 0.2.58 首轮 3 项因网络主机不可达而超时；1.7.0 全部通过 |
| 关键结论 | 两代版本的 history() / download() 列结构与索引语义一致；差异集中在 1.x 新增模块 | 据此本站对「列结构」类结论不做版本限定，对「新模块」类结论明确标注需要 1.x |
边界：以上只是本机、本时间窗的一次实测，不能外推为「某版本在全世界都如此」。网络可达性会随时段波动（本站实测同一版本在不同时间窗的失败项数不同），因此本站不把网络失败写成「某版本不支持某接口」。
Verify
升级前该核对什么：四条检查清单
把「版本」当成一个需要记录的环境参数，而不是随手装的东西。
② 先跑一次列结构断言
把期望的列集合写成断言（例如 set(df.columns) >= {"Open","High","Low","Close","Volume"}），升版本后先跑断言再跑业务代码。列结构在本站两代实测中是一致的，所以断言失败通常指向别的问题。
③ 升级前看 CHANGELOG
仓库 CHANGELOG.rst 按版本列出改动，例如 1.6.0 起「Yahoo 给出原因时不再声称 possibly delisted」、1.6.0 修了 repair=True 会永久把 GBp/ZAc/ILA 价格转成主货币的问题。这些是行为变化，不是文档措辞变化。
④ 把网络失败与代码失败分开
本站实测中出现的 Failed to connect to hk.yahoo.com port 443 是网络层问题，与版本、与 ticker 正确性都无关。排障顺序是：先确认主机可达 → 再看异常类型 → 最后才怀疑版本。
Pin it
怎么把版本钉住：三条省掉返工的工程习惯
版本问题不会当场报错，只会在几周后以「结果对不上」的形式出现，所以要在写代码时就钉住。
| 习惯 | 具体做法 | 它防的是什么 | 成本 |
|---|---|---|---|
| 固定依赖版本 | 在 requirements.txt 里写 yfinance==1.7.0，或至少写 yfinance>=1.7,<2 | 同一份代码在不同时间装出不同大版本（本站实测过 0.2.58 与 1.7.0 共存的情形） | 一次性，几秒钟 |
| 把环境信息写进产物 | 数据落盘时同时记录 yf.__version__、sys.executable、Python 与 pandas 版本 | 半年后无法回答「这份数据是用什么跑出来的」 | 一行代码 |
| 用独立环境隔离 | 用 venv 装取数依赖，不要和模型训练、回测框架挤在同一个环境里 | 依赖冲突（实测：同环境下 finrl 要求 yfinance<0.3，与 1.x 直接冲突） | 每个项目一个环境 |
| 升级前跑列结构断言 | 把期望列集合写成断言，升级后先跑断言再跑业务代码 | 接口行为微调导致的静默错误 | 写一次，长期复用 |
Repro
怎么向别人复现你的环境：一份最小记录模板
把下面这几行写进项目 README，别人（以及半年后的你）就能重建同一个环境。
# environment.txt —— 本项目取数环境的固定记录
python : 3.11.9
library : 1.7.0 # pip install <pkg>==1.7.0
pandas : 2.2.3
numpy : 2.4.6
curl_cffi : 0.15.0 # 1.2.1 起因 CVE 被强制 >=0.15
install_cmd : pip install <pkg>==1.7.0
verified_at : 2026-10-09
# 记录时务必包含解释器路径：同机可能存在多个副本
sys.executable : .venv/Scripts/python.exe
library.__file__ : .venv/Lib/site-packages/<pkg>/__init__.py| 记录项 | 为什么必须写 | 不写会怎样 |
|---|---|---|
| 解释器绝对路径 | 同机可能同时存在多个版本（本站实测过 0.2.58 与 1.7.0 共存） | 别人在错误的解释器上跑你的脚本，得到不同结果却找不到原因 |
| 库版本号 | 1.x 与 0.2.x 的能力面不同（config、WebSocket 等） | 代码在对方环境里 AttributeError |
| 关键依赖版本 | 依赖冲突是安装失败的主要来源（本站实测到 finrl 与 websockets 的约束冲突） | 装完才发现解析结果与自己环境不同 |
| 核验日期 | 数据源行为会随时间变化，网络可达性也会 | 把「当时可用」当成「永远可用」 |
FAQ
yfinance 常见问题
下面的回答都指向可核验的官方文件或本站实测；与官方表述冲突时，以官方仓库与 docs 为准。
yfinance 怎么安装？需要 Python 什么版本？
官方方式是 pip install yfinance，官方文档建议在虚拟环境里安装。但仓库并没有声明 requires-python：pyproject.toml 里没有该字段，PyPI 的 info.requires_python 也是空的，而 classifiers 里还列着 Python 3.6–3.13。所以「支持哪个 Python」只能靠实际安装结果判断，不要靠 classifiers。本站实测在 Python 3.11.9 上 1.7.0 安装成功并正常取数。
装完之后怎么确认装对了版本？
跑 import yfinance; print(yfinance.__version__)，再确认 yfinance.__file__ 指向你要用的环境。这一步很关键：本站实测同一台机器上同时存在两个 yfinance（EasyClaw 自带环境里的 0.2.58 与独立 venv 里的 1.7.0），如果解释器选错，import yfinance as yf; yf.config 会直接 AttributeError。
1.x 相对 0.2.x 是破坏性升级吗？
官方 1.0 的 CHANGELOG 原文写的是 No breaking changes, but some deprecation warnings.但本站用 dir(yf) 实测，1.6 及更早版本没有 config，raise_errors 参数也已被废弃（源码给出的提示是改用 yf.config.debug.hide_exceptions = False）。所以准确说法是：既有接口保留，新增能力主要靠新模块承载，旧写法会给 DeprecationWarning。
yfinance 依赖哪些包？为什么会装不上？
核心依赖为 BeautifulSoup4、curl_cffi、lxml、multitasking、numpy、pandas、peewee、platformdirs、protobuf、pytz、requests、websockets；可选的 repair extra 会额外引入 scipy 与 scikit-learn。实测最容易冲突的是 curl_cffi 与 websockets：CHANGELOG 记录了 1.2.1「Force curl_cffi>=0.15, because CVE」和 1.5.2「Fix yfinance breaking with curl_cffi>=0.16」。
能不能不用 curl_cffi 安装？
可以。官方文档给出了绕过方式：把 requirements.txt 里 curl_cffi 那一行过滤掉后安装依赖，再 pip install --no-deps yfinance。这条路径是 1.4.0「Make curl_cffi optional with fallback to requests」之后才成立的。
已经在用本机技能路线，需要自己装 yfinance 吗？
分两种情形：①只是想用免部署路线问数据问题，不需要自己装——本机已有 3 个技能在直接调用 yfinance 库（yahoo-finance-github、stock-price-checker、fp-dcf）；②要写自己的取数脚本、要控制复权口径与缓存位置，就装一个独立 venv。另外要如实说明：yfinance 项目与 EasyClaw 无已证实集成，这套技能体系里也不存在「安装 yfinance」这一技能路由。