yfinance 使用指南：用 Python 优雅地下载 Yahoo! Finance 市场数据-北京尧图网络

yfinance 使用指南用 Python 优雅地下载 Yahoo! Finance 市场数据【免费下载链接】yfinanceDownload market data from Yahoo! Finances API项目地址: https://gitcode.com/GitHub_Trending/yf/yfinance导读yfinance 是一个面向 Yahoo! Finance 公开 API 的 Python 市场数据下载库它提供了一套 Pythonic符合 Python 习惯的接口让你可以用几行代码获取股票历史行情、基本面数据、期权链、实时行情流、行业板块信息乃至市场筛选结果。本文以仓库 README.md 为骨架结合仓库内的官方示例doc/source/reference/examples/与源码实现完整讲解 yfinance 的安装方式、八大核心组件Ticker、Tickers、download、Market、WebSocket、Search、Sector/Industry、Screener的用法以及Calendars、Auth、代理等进阶能力帮助你快速搭建自己的行情数据管道。一、yfinance 是什么yfinance提供了一种 Pythonic 的方式来从 Yahoo! Finance 获取金融与市场数据。它的核心设计理念是以面向对象的方式封装 Yahoo 的公开 API让取数这件事足够简单直接——你不需要手写 HTTP 请求、处理 cookie 与 crumb 校验只需要创建对象、访问属性即可。从源码的顶层导出yfinance/init.py可以看到yfinance 对外开放的能力相当完整顶层导出类型用途Ticker类单个标的全量数据历史、财务、期权等Tickers类批量管理多个标的download函数一键下载多个标的的历史行情Market/MarketRegion类/枚举市场状态与摘要信息WebSocket/AsyncWebSocket类实时行情流同步/异步Search类报价与新闻搜索Lookup类标的查找Sector/Industry类行业板块信息EquityQuery/FundQuery/ETFQuery/screen类/函数构建查询并筛选市场Calendars类财报、IPO、拆股等事件日历Auth类登录态管理与订阅层级查询config/set_config配置全局配置代理、重试等这些正是 README 中 Main components主要组件一节的完整落地。二、安装从 PyPI 安装 yfinance 非常简单$ pip install yfinance安装后在 Python 中即可直接导入import yfinance as yf需要说明两点依赖说明yfinance 默认依赖curl_cffi作为 HTTP 传输层。如果希望不使用curl_cffi而回退到requests可以参考仓库文档 doc/source/advanced/install.rst 中的高级安装说明进行配置。底层会话约束从源码 yfinance/data.py 可以看到yfinance 通过YfData单例管理全局请求会话。缓存型会话如requests_cache以及非 curl_cffi/requests 的会话类型会被直接拒绝抛出YFDataException原因是缓存会破坏数据一致性——yfinance 自己就内置了 crumb、cookie 与响应缓存机制。三、核心组件一Ticker——单个标的数据中心Ticker是 yfinance 最常用的入口封装了单个股票、ETF、基金或指数的几乎所有公开数据。官方示例doc/source/reference/examples/ticker.py展示了它的典型用法import yfinance as yf dat yf.Ticker(MSFT) # 获取历史行情数据 dat.history(period1mo) # 期权链取第一个到期日 dat.option_chain(dat.options[0]).calls # 财务报表 dat.balance_sheet dat.quarterly_income_stmt # 日历信息财报日期、除息日等 dat.calendar # 综合信息市值、PE、行业等 dat.info # 分析师目标价 dat.analyst_price_targets # WebSocket 实时行情 dat.live()从源码结构看yfinance/ticker.pyTicker继承自TickerBaseyfinance/base.py其中history()拉取历史 OHLCV 数据支持period如1mo或start/end日期区间两种模式返回 pandas DataFrameoption_chain(dateNone, tzNone)通过 Yahoo 的/v7/finance/options/{ticker}接口获取期权数据返回包含calls、puts、underlying三个字段的 namedtuple。若指定的到期日不在dat.options列表中会抛出ValueError并列出可用到期日yfinance/ticker.py属性访问info、calendar、analyst_price_targets、major_holders、institutional_holders、isin等均为延迟加载属性首次访问时才会真正发起网络请求。3.1 常见属性速查除示例中的属性外Ticker还暴露了大量常用数据接口见 yfinance/ticker.py 与 yfinance/base.py属性/方法说明history()历史行情OHLCV可选actionsTrue附带分红拆股actions/dividends/splits/capital_gains公司行为数据financials/income_stmt/balance_sheet/cashflow三大财务报表及季度版quarterly_*info综合行情快照市值、PE、52 周高低等analyst_price_targets/recommendations分析师评级与目标价calendar财报与除息日历funds_data基金/ETF 专属数据见后文live()订阅该标的的 WebSocket 实时行情get_isin()查询 ISIN 代码四、核心组件二Tickers——批量管理多个标的当需要同时跟踪多个标的时使用Tickers可以一次性创建多个Ticker对象并按代码访问官方示例 doc/source/reference/examples/tickers.pyimport yfinance as yf tickers yf.Tickers(msft aapl goog) # 通过 .tickers 字典按代码访问自动转为大写 tickers.tickers[MSFT].info tickers.tickers[AAPL].history(period1mo) tickers.tickers[GOOG].actions # WebSocket 实时行情 tickers.live()从源码看yfinance/tickers.pyTickers内部还封装了download()方法本质上委托给multi.download()参数与下文download函数完全一致——也就是说Tickers既是对象容器也是批量取数的便捷入口。五、核心组件三download——一键批量下载历史行情yf.download()是 yfinance 最经典、最常用的函数级 API一行代码即可下载多标的历史数据import yfinance as yf data yf.download(SPY AAPL, period1mo)返回结果是一个多级索引MultiIndex的 pandas DataFrame默认按列group_bycolumn组织即顶层为价格字段Open/High/Low/Close/Volume下一层为标的代码。5.1 完整参数详解download()的完整签名定义在 yfinance/multi.py所有参数说明如下参数类型/默认值说明tickersstr, list要下载的标的列表。字符串可用空格或逗号分隔如SPY AAPL或SPY, AAPL也可传 list。支持 ISIN如US0378331005内部会自动转换为 tickerperiodstr默认1mo有效区间1d, 5d, 1mo, 3mo, 6mo, 1y, 2y, 5y, 10y, ytd, max。默认在未指定start/end时为1mo。period与start/end二选一intervalstr默认1d有效周期1m, 2m, 5m, 15m, 30m, 60m, 90m, 1h, 1d, 5d, 1wk, 1mo, 3mo。分钟级日内数据最多回溯 60 天。注意30m数据实际是从 Yahoo 拉取15m后重采样得到的以规避 Yahoo API 的 bugstart/endstrYYYY-MM-DD或 datetime起始日期包含如start2020-01-01的首个数据点就在当天结束日期不包含如end2023-01-01的最后数据点是2022-12-31。start默认 99 年前end默认当前group_bystr默认column按ticker或column分组组织 MultiIndexprepostbool默认False是否包含盘前盘后数据auto_adjustbool默认True是否自动复权所有 OHLC 数据back_adjustbool默认False是否使用后复权repairbool默认False是否检测货币单位 100 倍错乱currency unit 100x mixups并尝试修复——这是 yfinance 的特色数据修复功能仓库为其准备了大量测试用例见 tests/test_price_repair.py 与 tests/data/ 下的*-fixed.csv对照数据keepnabool默认False是否保留 Yahoo 返回的 NaN 行actionsbool默认False是否同时下载分红与拆股数据threadsbool / int默认True批量下载使用的线程数。True时自动取min(标的数据, CPU 核数 * 2)见 yfinance/multi.pyignore_tzbool合并不同时区数据时是否忽略时区部分。默认取决于interval日内数据分钟/小时级为False日线及以上为True同时控制返回索引的时区属性roundingbool默认False是否将数值四舍五入到 2 位小数timeoutNone 或 float默认10请求超时秒数支持小数如0.01sessionSession自定义请求会话对象multi_level_indexbool默认True是否总是返回 MultiIndex DataFrame5.2 底层执行流程从源码看yfinance/multi.pydownload()的执行分为几步将字符串 tickers 统一转为大写并去重ISIN 自动转换为 ticker若开启threads通过_multitasking并行发起下载并显示进度条所有标的数据下载完成后统一对齐时间索引并合并为 MultiIndex DataFrame。调试提示当开启 DEBUG 日志时yfinance 会自动关闭多线程和进度条yfinance/multi.py避免日志交错这在排查问题时非常有用。六、核心组件四Market——市场状态与摘要Market用于获取某个市场的整体状态开盘/收盘与摘要信息。官方示例doc/source/reference/examples/market.pyimport yfinance as yf EUROPE yf.Market(EUROPE) status EUROPE.status # 市场当前状态 summary EUROPE.summary # 市场摘要从源码看市场区域由MarketRegion枚举定义yfinance/init.py、yfinance/domain/market.pyMarket接受区域名称如EUROPE进行构造。该组件适合做交易日判断和市场概况类的应用——例如在交易策略启动前先检查目标市场是否处于交易时段。七、核心组件五WebSocket 与 AsyncWebSocket——实时行情流yfinance 提供同步与异步两套 WebSocket 客户端用于订阅实时行情定价数据流。官方示例提供了完整的两种写法doc/source/reference/examples/live_sync.py、doc/source/reference/examples/live_async.py。7.1 同步版 WebSocketimport yfinance as yf # 定义消息回调 def message_handler(message): print(Received message:, message) # # 方式一上下文管理器推荐 # with yf.WebSocket() as ws: ws.subscribe([AAPL, BTC-USD]) ws.listen(message_handler) # # 方式二手动管理 # ws yf.WebSocket() ws.subscribe([AAPL, BTC-USD]) ws.listen(message_handler)7.2 异步版 AsyncWebSocketimport asyncio import yfinance as yf # 定义消息回调 def message_handler(message): print(Received message:, message) async def main(): # # 方式一异步上下文管理器 # async with yf.AsyncWebSocket() as ws: await ws.subscribe([AAPL, BTC-USD]) await ws.listen() # # 方式二手动管理 # ws yf.AsyncWebSocket() await ws.subscribe([AAPL, BTC-USD]) await ws.listen() asyncio.run(main())从源码看yfinance/live.py、yfinance/live.py两个类均基于wss://streamer.finance.yahoo.com/?version2端点AsyncWebSocket继承自BaseWebSocket二者 API 对齐subscribe订阅代码列表、listen持续监听并回调消息。注意示例中同时订阅了股票AAPL与加密货币BTC-USD代码说明该流不局限于股票。另外Ticker.live()和Tickers.live()也封装了实时流入口见 yfinance/base.py 与 yfinance/tickers.py可以按对象粒度直接启动订阅。八、核心组件六Search——报价与新闻搜索Search用于搜索 Yahoo Finance 中的报价quotes、新闻news与研究内容research。官方示例doc/source/reference/examples/search.pyimport yfinance as yf # 获取报价列表 quotes yf.Search(AAPL, max_results10).quotes # 获取新闻列表 news yf.Search(Google, news_count10).news # 获取相关研究内容 research yf.Search(apple, include_researchTrue).researchSearch的构造参数支持max_results报价结果数量上限、news_count新闻数量与include_research是否包含研究内容三个属性quotes、news、research分别对应三类结果实现见 yfinance/search.py。该组件适合做关键词驱动的投研信息聚合例如按行业热点收集新闻。九、核心组件七Sector 与 Industry——行业板块信息Sector与Industry分别封装 Yahoo 的行业板块数据。官方示例doc/source/reference/examples/sector_industry.pyimport yfinance as yf tech yf.Sector(technology) software yf.Industry(software-infrastructure) # 公共信息Sector 与 Industry 通用 tech.key tech.name tech.symbol tech.ticker # 与该板块关联的 Ticker 对象 tech.overview tech.top_companies tech.research_reports # Sector 独有信息 tech.top_etfs tech.top_mutual_funds tech.industries # Industry 独有信息 software.sector_key software.sector_name software.top_performing_companies software.top_growth_companies9.1 与 Ticker 双向联动板块与个股之间可以互相转换官方示例 doc/source/reference/examples/sector_industry_ticker.pyimport yfinance as yf # Ticker - Sector 和 Industry msft yf.Ticker(MSFT) tech yf.Sector(msft.info.get(sectorKey)) software yf.Industry(msft.info.get(industryKey)) # Sector/Industry - Ticker获取代表性标的 tech_ticker tech.ticker tech_ticker.info software_ticker software.ticker software_ticker.history()这个双向转换能力非常实用你可以从任意个股出发拿到它所属的板块与行业再借助top_companies、top_etfs、top_mutual_funds等属性扩展出同板块候选池从而构建行业轮动或同业对比的分析流程。相关实现位于 yfinance/domain/sector.py 与 yfinance/domain/industry.py。十、核心组件八EquityQuery 与 Screener——市场筛选EquityQuery以及FundQuery、ETFQuery用于构建结构化筛选条件screen()函数则执行筛选。从源码看yfinance/screener/query.py值运算EQ等于、IS-IN属于、BTWN介于、GT大于、LT小于、GTE大于等于、LTE小于等于逻辑组合AND、OR。例如可以基于地区region、行业sector、交易所exchange等条件构造股票筛选器然后通过 yfinance/screener/screener.py 中的screen(query, offset, size, sortField, sortAsc, ...)执行返回符合条件的标的列表。该模块还预置了一批常用筛选查询PREDEFINED_SCREENER_QUERIES见 yfinance/init.py可直接用于快速筛选最活跃、涨幅榜等场景Calendars示例中就曾用到screen(queryMOST_ACTIVES)。十一、进阶能力Calendars、FundsData、Auth 与代理除了 README 列出的八大组件yfinance 还提供了几项值得掌握的进阶能力。11.1 Calendars——事件日历Calendars提供财报、IPO、拆股、经济事件四类日历数据并支持按市值、活跃度过滤官方示例 doc/source/reference/examples/calendars.pyimport yfinance as yf from datetime import datetime, timedelta # 默认初始化今天 7 天 calendar yf.Calendars() # 只取今天之后 1 天的事件 tomorrow datetime.now() timedelta(days1) calendar yf.Calendars(endtomorrow) # 默认查询访问属性即触发数据获取 calendar.earnings_calendar calendar.ipo_info_calendar calendar.splits_calendar calendar.economic_events_calendar # 手动查询带自定义参数 calendar.get_earnings_calendar( market_cap100_000_000, # 过滤掉小市值公司 filter_most_activeTrue, # 只显示活跃交易标的内部使用 screen(queryMOST_ACTIVES) ) # 实战示例找出临近发布但尚未披露财报的公司 today datetime.now() is_friday today.weekday() 4 day_after_tomorrow today timedelta(days4 if is_friday else 2) calendar yf.Calendars(today, day_after_tomorrow) df calendar.get_earnings_calendar(limit100) unreported_df df[df[Reported EPS].isnull()]11.2 FundsData——基金/ETF 专属数据对于 ETF 或共同基金标的Ticker.funds_data提供持仓与运作信息官方示例 doc/source/reference/examples/funds_data.pyimport yfinance as yf spy yf.Ticker(SPY) data spy.funds_data data.description # 基金描述 data.fund_overview # 基金概览 data.fund_operations # 运作信息 data.asset_classes # 资产类别 data.top_holdings # 前十大持仓 data.equity_holdings # 股票持仓明细 data.bond_holdings # 债券持仓明细 data.bond_ratings # 债券评级 data.sector_weightings # 行业权重该能力让 yfinance 从股票工具扩展到了基金研究工具相关实现位于 yfinance/scrapers/funds.py。11.3 Auth——登录态与会话管理Auth允许你将浏览器中获得的登录 Cookie 注入会话从而以登录用户身份请求数据官方示例 doc/source/reference/examples/auth.pyimport yfinance as yf import os auth yf.Auth() # 设置从浏览器获取的登录 Cookie。该调用会存储、实时校验并返回登录结果。 if auth.set_login_cookies(os.getenv(COOKIE_T), os.getenv(COOKIE_Y)): print(Logged in) else: print(Invalid or expired cookies) # 此后所有发往 Yahoo Finance 的请求都携带该登录态。 # 随时重新校验实时登录状态每次调用都会重新查询不做缓存。 auth.check_login() # - True / False # 查询账户的订阅层级。 auth.subscription_tier() # - gold / silver / bronze / free / None # 访问用户信息。 auth.user # - {guid: ...} or None从源码看yfinance/data.pyset_login_cookies会以线程安全的方式把T、Y两个 Cookie 写入全局会话并清除旧 crumbcrumb 可能与匿名态不匹配强制在下一请求重新生成与当前 Cookie 匹配的 crumb从而让登录态干净生效。同时会话的 cookie 策略切换basic/csrf在登录态下不会清空用户 Cookie 锅避免静默登出yfinance/data.py。11.4 代理Proxy支持所有请求级接口都支持proxy参数官方示例 doc/source/reference/examples/proxy.pyimport yfinance as yf msft yf.Ticker(MSFT) msft.history(..., proxyPROXY_SERVER) msft.get_actions(proxyPROXY_SERVER) msft.get_dividends(proxyPROXY_SERVER) msft.get_splits(proxyPROXY_SERVER) msft.get_capital_gains(proxyPROXY_SERVER) msft.get_balance_sheet(proxyPROXY_SERVER) msft.get_cashflow(proxyPROXY_SERVER) msft.option_chain(..., proxyPROXY_SERVER)此外也可以通过全局配置设置代理yf.config.network.proxy proxy旧的yf.set_config(proxy...)方式已被标记为弃用见 yfinance/init.py。底层实现会将字符串代理统一规范化为{http: ..., https: ...}字典后挂到会话上yfinance/data.py。十二、底层架构YfData 单例与缓存机制理解 yfinance 的底层架构有助于你更好地使用它。从源码看yfinance/data.pyYfData是单例通过SingletonMeta元类实现整个进程共享一个请求会话、一份 cookie 和一份 crumb这既保证了多线程并发下的数据一致性也大幅提升了请求效率cookie/crumb 只需获取一次。自带响应缓存YfData通过lru_cache装饰器缓存数据yfinance/data.py把字典/列表参数冻结后作为缓存键默认缓存容量为 64。cookie 策略自动切换默认使用basic策略失败时回退到csrfyfinance/data.py。瞬时错误重试对TimeoutError、ConnectionError等瞬时网络错误yfinance/data.py请求层会自动重试。这正是上一节提到缓存型会话会被拒绝的原因yfinance 已经内置了完整的缓存与重试链路外部再叠加requests_cache反而会引入脏数据。十三、调试与测试排查问题时可以开启调试日志import yfinance as yf yf.enable_debug_mode()该函数由 yfinance/utils.py 提供开启后能观察每次请求的 URL、cookie 策略切换与重试过程yfinance/data.py 中的日志即由此输出。仓库自带完整测试套件tests/其中与下载、价格修复相关的重点测试文件包括tests/test_prices.py——历史行情下载与复权逻辑tests/test_price_repair.py——repairTrue的价格修复逻辑配套 tests/data/ 目录下大量*-bad-*.csv/*-fixed.csv成对数据覆盖了分红错乱bad-div、拆股错乱bad-stock-split、100 倍单位错乱100x-error等真实场景tests/test_ticker.py、tests/test_multi.py、tests/test_live.py——分别覆盖Ticker、批量下载与 WebSocket 功能。如果你想运行测试验证环境可按 doc/source/development/running.rst 与 doc/source/development/testing.rst 中的说明操作。十四、法律与合规提示最后必须强调 README 中明确说明的事项商标声明Yahoo!、Y!Finance 与 Yahoo! finance 是 Yahoo, Inc. 的注册商标。非官方工具yfinance 与 Yahoo, Inc. 没有任何从属、背书或审查关系。它是一个使用 Yahoo 公开 API 的开源工具仅用于研究与教育目的。使用条款在使用下载的数据前你应当自行查阅 Yahoo! 的服务条款确认你对所下载数据的使用权利。Yahoo! Finance API 仅限个人用途。开源协议yfinance 基于Apache Software License分发详见 LICENSE.txt。如果你希望参与社区共建、提交 Bug 报告或贡献代码可以参考 CONTRIBUTING.md 中的指引。【免费下载链接】yfinanceDownload market data from Yahoo! Finances API项目地址: https://gitcode.com/GitHub_Trending/yf/yfinance创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

yfinance 使用指南：用 Python 优雅地下载 Yahoo! Finance 市场数据

相关推荐

React事件处理机制与最佳实践解析

wezterm 的 normalize_output_to_unicode_nfc：让终端输出统一为 Unicode NFC 规范化形式

PHP 8新特性解析：注解、纤程与字符串处理实战

更多资讯

Lexical Markdown 集成指南：@lexical/markdown 的导入导出、快捷键与 Transformers 深度解析

嵌入式开发板完整使用流程：从硬件准备到外设联调的七步闭环

SadTalker 安装教程：一张人像加一段音频，5 步生成说话视频

Actual 怎么在银行账户导入 CSV 文件时设置日期格式与收支分列

LunaTranslator 快速上手：按游戏类型选捕获方式的 Galgame 实时翻译完整指南

RP2040 DMA寄存器详解：Pico底层实时开发硬核指南

今日更新

SpacetimeDB C++ 模块库实战：用 C++20 在数据库内构建 WebAssembly 模块

别踩雷！不是所有 AI 写作工具都靠谱，2026 高校认可工具精选

SSM+MySQL幼儿园管理系统源码解析：从部署到优化

本周精选

超人会飞不算本事：系统稳定依赖清晰规则与边界设计

超人VS蜘蛛侠：拆解超级IP的影响力与传播方法论

基于CNN的调制信号识别：MATLAB实现时频图分类实战

本月热门

基于YOLO的焊缝缺陷检测：从数据标注到工业部署全流程实践

分布式服务的决策记录

创业产品的首版范围

读完文章，想聊聊您的网站？