yfinance手把手指南：三步跑通第一条行情，附避坑与进阶技巧
项目地址: https://gitcode.com/GitHub_Trending/yf/yfinance yfinance 是一个从 Yahoo Finance 接口抓取市场数据的 Python 库：股票、ETF、指数、外汇的行情和财务报表，一行代码就能拉成 pandas 的 DataFrame。对做量化研究、写分析脚本、或者只是想在 Notebook 里看一眼某只票的人来说，它几乎是绕不开的起步工具。
这篇文章不按"常见问题清单"来讲，而是带你走一条完整路径：装好环境 → 拉到第一条数据 → 用一个真实任务串起常用接口 → 知道哪里容易踩坑 → 最后上两个提效手段。
一、装好环境并确认能跑
先装包，版本建议锁定一下，避免不同机器上行为不一致：
pip install yfinance
装完用两行确认导入正常、版本到位：
import yfinance as yf
print(yf.__version__)
print(yf.Search("apple").quotes[:2]) # 顺便试一下搜索接口
能打印出版本号、搜到 AAPL，环境就算通了。这个库的所有能力都从 yf. 这一个入口展开，后面用到的接口其实就十几个。
二、三步拿到第一条行情
yf.download() 是最常用的入口，参数直接写在源码注释里，可读性不错：yfinance/multi.py。
第一步，拿一个月的日线：
df = yf.download("AAPL", period="1mo", progress=False)
print(df.tail())
第二步，换时间范围。日期范围有两种写法，period 二选一即可：
| 写法 | 可选值 | 适用场景 |
|---|---|---|
period= | 1d / 5d / 1mo / 3mo / 6mo / 1y / 2y / 5y / 10y / ytd / max | 以"最近 N 天"为锚点 |
start= + end= | YYYY-MM-DD 字符串 | 固定区间回测 |
第三步，换粒度。interval 支持 1m、5m、15m、1h、1d、1wk、1mo 等，分钟级和小时级数据注意只能取最近约 60 天：
df = yf.download("AAPL", period="5d", interval="1h", progress=False)
返回的是带 Open / High / Low / Close / Adj Close / Volume 列的时间序列，时区索引默认已处理，直接丢给 matplotlib 或回测框架都能用。
三、用 Ticker 完成一个真实任务
下载一批票的行情用 download，但要看单只票的细节时，Ticker 更顺手，接口都在 yfinance/ticker.py 里：
t = yf.Ticker("AAPL")
hist = t.history(period="1y", repair=True) # 日线
fi = t.fast_info # 轻量实时信息，比 info 快
stmt = t.income_stmt # 利润表
t.dividends/t.splits/t.actions：分红、拆股、两者合并t.balance_sheet/t.cash_flow：资产负债表、现金流量表t.fast_info和t.info的区别：前者只拉实时快照，字段少但请求快；后者信息全但更重
一个真实任务示例——给 4 只科技股做一年交叉对比：
data = yf.download(["AAPL", "MSFT", "GOOGL", "TSLA"],
period="1y", interval="1d",
group_by="column", auto_adjust=True)
ret = data["Close"].pct_change().dropna()
print(ret.tail())
几个参数的作用值得记住：
group_by="column"：默认按列分组，多只票时指标列嵌套在每只票下面；改成"ticker"则反过来auto_adjust：默认True，价格自动按分红拆股复权repair：默认False，打开后会自动修一些雅虎源数据的问题，下一节细说keepna：默认False，自动丢掉空行
四、避坑：数据不对时先查这三处
用雅虎这个免费数据源，绝大多数"数据怪怪的"问题都能归到三类 ⚠️
1. 请求超时或被限流。 先开调试模式看它到底卡在哪一步：
yf.enable_debug_mode()
再给网络层配上重试和代理（配置入口是 yf.config）：
yf.config.network.retries = 3
yf.config.network.proxy = "http://127.0.0.1:7890"
2. 价格或复权明显不对。 雅虎的非美股数据偶尔会缺分红/拆股调整，甚至出现货币单位差 100 倍的错。这时把 repair=True 打开，返回结果会多一列 Repaired? 标出被修过的行；修完后想确认币种，以 t.history_metadata['currency'] 为准，而不是 t.info 里的字段。具体能修哪些场景，doc/source/advanced/price_repair.rst 里有配图说明。
3. 分钟级数据"只有六十天"。 这不是 bug，是上游限制：interval 在 1m~1h 这一档时只能取最近 60 天。需要更长历史的分钟级数据，只能自己按天分段循环拉取再拼接。
| 症状 | 先查什么 |
|---|---|
| 下载卡住、无输出 | yf.enable_debug_mode() 看日志，配 retries |
| 价格对不上行情软件 | repair=True，看 Repaired? 列 |
| 币种/数量级怪异 | history_metadata['currency'] |
| 分钟数据拉不到更早 | 上游 60 天限制，分段拉取 |
五、提效进阶：把零散调用变成数据管道
缓存。 这个库会缓存时区等信息以减少重复请求，默认放在用户缓存目录下，想自定义路径（比如挪到 SSD 或持久卷）：
yf.set_tz_cache_location("./my-cache")
筛选器。 不想手动列票的话，yf.screen() 配合 EquityQuery / FundQuery / ETFQuery 可以按条件筛出候选票，PREDEFINED_SCREENER_QUERIES 里还有现成的预设条件模板。写查询条件前可以先翻翻 doc/source/reference/examples/search.py 这类参考脚本，doc/source/reference/examples/ 下还有日历、盘口、代理等场景的示例。
实时行情。 不满足于"拉一次"的话，yf.WebSocket 和 yf.AsyncWebSocket 提供推送式报价，订阅逻辑简单：
ws = yf.WebSocket()
ws.subscribe(["AAPL", "MSFT"])
订阅需要周期性刷新（约 15 秒一次），库内部已处理，断线重连后要重新 subscribe。
顺手的周边接口。 yf.Calendars() 查各市场交易日历，yf.Market()、yf.Sector()、yf.Industry() 按地区、板块、行业浏览标的，做数据校验时很省心。
想继续往下挖源码的话，项目结构很直白：yfinance/ 是主包，scrapers/ 下是各数据抓取的实现，screener/ 是筛选逻辑，tests/ 里存了大量真实修复前后的对照数据，可以当文档读。项目采用 main / dev 双主干加 feature、bugfix 分支的开发模式，版本按 main 上的打点发布：
到这里，从 pip install 到批量下载、单票深挖、排障和筛选推送，你已经把 yfinance 日常 90% 的用法过了一遍。剩下的事很简单：挑一个你真正关心的问题（回测某策略、做一份行业对比），用上面的接口把它做出来，踩到的每个新坑都会反过来让你更熟这个库。
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
