yfinance 深度解析教程 (Python)
yfinance 是一个非常流行的 Python 库，允许用户从 Yahoo Finance 下载金融市场数据。它提供了一种简单方便的方式来获取股票价格、历史数据、基本面信息、期权数据等。本教程将深入探讨 yfinance 的核心功能和高级用法。
目录
- 简介与安装
- 1.1 什么是 yfinance?
- 1.2 为什么选择 yfinance?
- 1.3 安装 yfinance
- 核心对象：
Ticker- 2.1 创建 Ticker 对象
- 2.2 获取股票信息 (
info)
- 获取历史市场数据 (
history)- 3.1 基本用法 (周期
period) - 3.2 指定时间范围 (
start,end) - 3.3 不同时间间隔 (
interval) - 3.4 数据格式 (Pandas DataFrame)
- 3.5 其他参数 (如
actions)
- 3.1 基本用法 (周期
- 获取基本面数据
- 4.1 财务报表 (
financials,balance_sheet,cashflow) - 4.2 盈利 (
earnings) - 4.3 季度数据
- 4.1 财务报表 (
- 获取其他关键数据
- 5.1 股票行为 (
actions,dividends,splits) - 5.2 持股信息 (
major_holders,institutional_holders) - 5.3 推荐评级 (
recommendations) - 5.4 公司日历与盈利日期 (
calendar,earnings_dates) - 5.5 ISIN 代码 (
isin) - 5.6 相关新闻 (
news)
- 5.1 股票行为 (
- 获取期权数据
- 6.1 获取期权到期日 (
options) - 6.2 获取特定到期日的期权链 (
option_chain)
- 6.1 获取期权到期日 (
- 处理多个 Ticker (
Tickers)- 7.1 创建 Tickers 对象
- 7.2 批量下载历史数据
- 7.3 访问单个 Ticker 数据
- 7.4 使用
yf.download()批量下载
- 高级技巧与注意事项
- 8.1 错误处理 (无效 Ticker)
- 8.2 数据可视化 (简单示例)
- 8.3 代理设置 (Proxy)
- 8.4 请求频率限制
- 总结
1. 简介与安装
1.1 什么是 yfinance?
yfinance 是一个开源的 Python 库，它最初是作为 pandas-datareader 库修复雅虎财经 API 变化的解决方案而创建的，后来发展成为一个独立且功能强大的库，专门用于从 Yahoo Finance 获取数据。
1.2 为什么选择 yfinance?
- 免费: 无需 API 密钥即可访问大量金融数据。
- 易用: API 设计简洁直观。
- 功能丰富: 支持多种数据类型（历史价格、基本面、期权等）。
- 与 Pandas 集成: 返回的数据通常是 Pandas DataFrame 或 Series 格式，方便后续分析。
1.3 安装 yfinance
使用 pip 可以轻松安装：
pip install yfinance --upgrade --no-cache-dir
建议加上 --upgrade --no-cache-dir 以确保安装最新版本并避免缓存问题。
同时，我们通常需要 pandas 来处理数据，如果未安装，也一并安装：
pip install pandas
2. 核心对象：Ticker
yfinance 的主要入口点是 Ticker 类。你需要为你想要获取数据的每个金融工具（股票、ETF、指数等）创建一个 Ticker 实例。
2.1 创建 Ticker 对象
import yfinance as yf
import pandas as pd # 通常会用到 pandas
# 创建一个代表苹果公司 (AAPL) 的 Ticker 对象
aapl = yf.Ticker("AAPL")
# 创建一个代表微软公司 (MSFT) 的 Ticker 对象
msft = yf.Ticker("MSFT")
# 也可以获取其他市场的股票，例如腾讯控股 (0700.HK)
tencent = yf.Ticker("0700.HK")
# 获取指数，例如标普 500 (^GSPC)
sp500 = yf.Ticker("^GSPC")
print(aapl)
# 输出类似: yfinance.Ticker object <AAPL>
这里的 “AAPL”, “MSFT”, “0700.HK”, “^GSPC” 就是所谓的 Ticker Symbol（股票代码）。你需要知道你感兴趣的金融工具在 Yahoo Finance 上的代码。
2.2 获取股票信息 (info)
info 属性返回一个包含该股票大量信息的 Python 字典。
# 获取苹果公司的详细信息
aapl_info = aapl.info
# 查看信息字典中的部分内容
print(f"公司名称: {aapl_info.get('longName', 'N/A')}")
print(f"所在行业: {aapl_info.get('industry', 'N/A')}")
print(f"所在板块: {aapl_info.get('sector', 'N/A')}")
print(f"公司简介: {aapl_info.get('longBusinessSummary', 'N/A')[:100]}...") # 只显示前100个字符
print(f"市值: {aapl_info.get('marketCap', 'N/A')}")
print(f"市盈率 (TTM): {aapl_info.get('trailingPE', 'N/A')}")
print(f"远期市盈率: {aapl_info.get('forwardPE', 'N/A')}")
print(f"股息率: {aapl_info.get('dividendYield', 'N/A')}")
# info 字典包含非常多的字段，你可以打印所有键来看看
# print(aapl_info.keys())
注意: info 字典中的字段并非对所有 Ticker 都完整可用，某些字段可能缺失（返回 None 或不存在）。使用 .get(key, default_value) 是更安全的访问方式。
3. 获取历史市场数据 (history)
这是 yfinance 最常用的功能之一，用于获取 OHLCV（开盘价、最高价、最低价、收盘价、成交量）数据。
3.1 基本用法 (周期 period)
history() 方法可以通过 period 参数指定获取数据的时间跨度。
# 获取苹果公司过去一年的日线数据
hist_1y = aapl.history(period="1y")
print("过去一年的日线数据 (前5条):")
print(hist_1y.head())
# 可用的 period 值包括: "1d", "5d", "1mo", "3mo", "6mo", "1y", "2y", "5y", "10y", "ytd" (年初至今), "max" (所有可用数据)
hist_max = aapl.history(period="max")
print(f"\n获取了 {len(hist_max)} 条历史数据 (从 {hist_max.index.min()} 到 {hist_max.index.max()})")
3.2 指定时间范围 (start, end)
也可以使用 start 和 end 参数指定具体的开始和结束日期（格式通常为 “YYYY-MM-DD”）。
# 获取 2023 年全年的日线数据
hist_2023 = aapl.history(start="2023-01-01", end="2024-01-01") # end日期不包含
print("\n2023 年全年日线数据 (后5条):")
print(hist_2023.tail())
3.3 不同时间间隔 (interval)
interval 参数用于指定数据的时间频率。
# 获取过去 5 天的 1 分钟 K 线数据
# 注意：分钟级别的数据获取有时间范围限制，通常只能获取最近几十天的数据
hist_5d_1m = aapl.history(period="5d", interval="1m")
print("\n过去 5 天的 1 分钟 K 线数据 (前5条):")
print(hist_5d_1m.head())
# 可用的 interval 值包括:
# 分钟级别: "1m", "2m", "5m", "15m", "30m", "60m", "90m"
# 小时级别: "1h" (注意: 60m 和 1h 可能略有不同)
# 日线及以上: "1d", "5d", "1wk", "1mo", "3mo"
# 获取过去 6 个月的周线数据
hist_6mo_wk = aapl.history(period="6mo", interval="1wk")
print("\n过去 6 个月的周线数据 (前5条):")
print(hist_6mo_wk.head())
重要提示:
- 分钟级别 (
1m,2m等) 的数据通常只能获取最近 7 天（对于1m）或 60 天（对于其他分钟级别）的数据。 - 请求过于频繁或数据量过大可能导致 Yahoo Finance 暂时阻止你的 IP。
3.4 数据格式 (Pandas DataFrame)
history() 方法返回的是一个 Pandas DataFrame，索引是日期（或时间戳），列包括：
Open: 开盘价High: 最高价Low: 最低价Close: 收盘价Volume: 成交量Dividends: 股息 (如果当天有派息)Stock Splits: 股票分割比例 (如果当天有分割)
print("\n历史数据 DataFrame 的列名:")
print(hist_1y.columns)
print("\n历史数据 DataFrame 的索引类型:")
print(type(hist_1y.index))
3.5 其他参数 (如 actions)
默认情况下，Dividends 和 Stock Splits 列包含在内。你也可以通过 actions=True (默认) 或 actions=False 控制是否获取这些信息。还有其他参数如 auto_adjust (自动调整价格以反映股息和拆分，默认为 True) 等，可以查阅文档了解更多。
# 不获取股息和拆分信息
hist_no_actions = aapl.history(period="1y", actions=False)
print("\n不包含 actions 的列名:")
print(hist_no_actions.columns)
# 获取未调整的价格 (会多出 'Adj Close' 列，表示前复权收盘价)
hist_unadjusted = aapl.history(period="1y", auto_adjust=False)
print("\n未自动调整价格的列名:")
print(hist_unadjusted.columns)
print(hist_unadjusted.head())
4. 获取基本面数据
yfinance 提供了访问公司财务报表和其他基本面数据的方法。
4.1 财务报表 (financials, balance_sheet, cashflow)
这些方法返回包含年度和季度财务报表的 Pandas DataFrame。
# 获取年度损益表 (Income Statement)
financials = aapl.financials
print("\n年度损益表 (部分):")
print(financials) # DataFrame 的列是年份或季度
# 获取年度资产负债表 (Balance Sheet)
balance_sheet = aapl.balance_sheet
print("\n年度资产负债表 (部分):")
print(balance_sheet.head())
# 获取年度现金流量表 (Cash Flow Statement)
cashflow = aapl.cashflow
print("\n年度现金流量表 (部分):")
print(cashflow.head())
4.2 盈利 (earnings)
这个属性似乎已被整合或弃用，更常用的查看盈利信息的方式是通过 financials 或 calendar / earnings_dates。旧版本可能有 aapl.earnings。
4.3 季度数据
默认情况下，上述财务报表方法返回年度数据。可以通过相应的 quarterly_ 属性获取季度数据。
# 获取季度损益表
q_financials = aapl.quarterly_financials
print("\n季度损益表 (部分):")
print(q_financials)
# 获取季度资产负债表
q_balance_sheet = aapl.quarterly_balance_sheet
print("\n季度资产负债表 (部分):")
print(q_balance_sheet.head())
# 获取季度现金流量表
q_cashflow = aapl.quarterly_cashflow
print("\n季度现金流量表 (部分):")
print(q_cashflow.head())
5. 获取其他关键数据
Ticker 对象还提供了许多其他有用的属性。
5.1 股票行为 (actions, dividends, splits)
actions: 返回一个包含所有股息和股票分割记录的 DataFrame。dividends: 只返回股息记录 (Series)。splits: 只返回股票分割记录 (Series)。
# 获取所有历史行为
actions = aapl.actions
print("\n股票行为 (股息与拆分):")
print(actions.tail()) # 显示最近的行为
# 获取股息历史
dividends = aapl.dividends
print("\n股息历史 (最近 5 条):")
print(dividends.tail())
# 获取拆分历史
splits = aapl.splits
print("\n股票分割历史:")
print(splits)
5.2 持股信息 (major_holders, institutional_holders)
major_holders: 主要股东信息 (通常是内部人士和持股比例较大的股东)。institutional_holders: 机构持股者信息。
# 获取主要股东信息
major_holders = aapl.major_holders
print("\n主要股东:")
print(major_holders)
# 获取机构持股者信息
inst_holders = aapl.institutional_holders
print("\n机构持股者 (前 10):")
print(inst_holders.head(10))
注意: 这些持股数据更新可能不及时，且并非对所有 Ticker 都可用。
5.3 推荐评级 (recommendations)
获取分析师对该股票的推荐评级历史。
recommendations = aapl.recommendations
print("\n分析师推荐评级 (最近 10 条):")
print(recommendations.tail(10))
DataFrame 通常包含日期、评级机构、评级变化（例如 从 Buy 到 Strong Buy）等信息。
5.4 公司日历与盈利日期 (calendar, earnings_dates)
calendar: 通常包含下一次盈利发布的日期范围和相关事件。earnings_dates: 提供历史上的盈利公告日期、EPS 预期和实际值。
# 获取公司日历 (如下次财报日期)
calendar = aapl.calendar
print("\n公司日历 (下次财报):")
print(calendar)
# 获取历史盈利日期信息
try:
earnings_dates = aapl.earnings_dates
print("\n历史盈利日期 (最近几次):")
print(earnings_dates.tail())
except Exception as e:
print(f"\n获取盈利日期失败: {e}") # 有时可能因数据不可用而出错
5.5 ISIN 代码 (isin)
获取股票的国际证券识别码 (ISIN)。
isin = aapl.isin
print(f"\nAAPL 的 ISIN 代码: {isin}")
# 对于非美国股票，这个可能更有用
# tencent_isin = tencent.isin
# print(f"0700.HK 的 ISIN 代码: {tencent_isin}")
注意: isin 属性有时可能返回 - 或空值，如果 Yahoo Finance 没有提供该数据。
5.6 相关新闻 (news)
获取与该 Ticker 相关的最新新闻标题和链接。
news = aapl.news
print("\n相关新闻 (部分):")
if news: # 检查列表是否为空
for item in news[:5]: # 只显示前 5 条
print(f"- 标题: {item.get('title')}")
print(f" 发布者: {item.get('publisher')}")
print(f" 链接: {item.get('link')}")
# print(f" 发布时间: {pd.to_datetime(item.get('providerPublishTime'), unit='s')}") # 时间戳转换
else:
print("未能获取到相关新闻。")
新闻列表包含字典，每个字典代表一条新闻，包含标题 (title)、链接 (link)、发布者 (publisher)、发布时间 (providerPublishTime - Unix时间戳) 等信息。
6. 获取期权数据
yfinance 也可以用来获取股票的期权链数据。
6.1 获取期权到期日 (options)
options 属性返回一个包含所有可用期权到期日的元组。
# 获取苹果公司所有可用的期权到期日
try:
option_dates = aapl.options
print("\n可用的期权到期日 (前几个):")
print(option_dates[:5])
except Exception as e:
print(f"\n获取期权到期日失败 (可能该 Ticker 没有期权): {e}")
6.2 获取特定到期日的期权链 (option_chain)
使用 option_chain() 方法，并传入一个到期日字符串，可以获取该日期的看涨 (Calls) 和看跌 (Puts) 期权链。
if option_dates: # 确保我们获取到了到期日
# 获取第一个到期日的期权链
first_expiry = option_dates[0]
opt_chain = aapl.option_chain(first_expiry)
# 期权链对象包含 .calls 和 .puts 两个 DataFrame
calls = opt_chain.calls
puts = opt_chain.puts
print(f"\n{first_expiry} 到期的看涨期权 (部分):")
print(calls.head()) # 显示前几行看涨期权数据
print(f"\n{first_expiry} 到期的看跌期权 (部分):")
print(puts.head()) # 显示前几行看跌期权数据
# 查看期权 DataFrame 的列名，了解包含哪些信息
print("\n看涨期权数据列名:")
print(calls.columns)
# 通常包含: contractSymbol, lastTradeDate, strike, lastPrice, bid, ask, change, percentChange, volume, openInterest, impliedVolatility, inTheMoney, contractSize, currency
注意: 期权数据可能比较庞大，获取时可能需要一些时间。
7. 处理多个 Ticker (Tickers)
如果你需要同时处理多个股票代码，使用 Tickers 类比为每个代码单独创建 Ticker 对象更高效，尤其是在批量下载历史数据时。
7.1 创建 Tickers 对象
将多个 Ticker Symbol 字符串（用空格分隔）或一个列表传递给 yf.Tickers()。
# 创建包含多个股票代码的 Tickers 对象
tickers_list = ["AAPL", "MSFT", "GOOG", "AMZN"]
tickers = yf.Tickers(" ".join(tickers_list)) # 或者直接 yf.Tickers("AAPL MSFT GOOG AMZN")
print(tickers)
# 输出类似: yfinance.Tickers object <AAPL,MSFT,GOOG,AMZN>
7.2 批量下载历史数据
Tickers 对象的 history() 方法可以一次性下载所有 Ticker 的历史数据。返回的 DataFrame 使用多层列索引 (MultiIndex)，第一层是 Ticker Symbol，第二层是 OHLCV 等数据字段。
# 批量获取过去一个月的数据
multi_hist = tickers.history(period="1mo")
print("\n批量获取的历史数据 (部分):")
print(multi_hist.head())
# 查看列索引结构
print("\n多层列索引:")
print(multi_hist.columns)
# 访问特定股票的特定列数据
print("\n访问 AAPL 的收盘价:")
print(multi_hist['AAPL']['Close'].head())
# 或者使用 stack() 方法转换数据结构，更方便按 Ticker 分组处理
# stacked_hist = multi_hist.stack(level=0).reset_index().rename(columns={'level_1': 'Ticker'})
# print("\n转换后的数据结构:")
# print(stacked_hist.head())
7.3 访问单个 Ticker 数据
Tickers 对象内部包含一个字典 tickers.tickers，其键是 Ticker Symbol，值是对应的 Ticker 对象。你可以通过这个字典访问单个 Ticker 的所有方法和属性。
# 访问 Tickers 对象中的 Google (GOOG) Ticker 对象
goog_ticker = tickers.tickers['GOOG']
# 获取 Google 的 info
goog_info = goog_ticker.info
print(f"\nGoogle 的公司名称: {goog_info.get('longName')}")
# 获取 Google 的财务数据
goog_financials = goog_ticker.financials
print("\nGoogle 的年度损益表 (部分):")
print(goog_financials.head())
这种方式在需要获取不同类型数据（如某些股票的历史数据，另一些股票的基本面信息）时很有用，但如果是统一获取同一种数据（如所有股票的历史收盘价），直接使用 Tickers 对象的批量方法通常更优。
7.4 使用 yf.download() 批量下载
yfinance 还提供了一个便捷的顶层函数 yf.download()，专门用于批量下载历史数据，通常比 Tickers.history() 更常用且可能更稳定。
# 使用 yf.download() 批量下载历史数据
data = yf.download("NVDA TSLA NFLX", start="2024-01-01", end="2024-04-01")
print("\n使用 yf.download() 获取的数据 (部分):")
print(data.head())
# download 返回的 DataFrame 默认按数据字段分组 (Open, High, Low, Close, Adj Close, Volume)
print("\nyf.download() 返回的列索引:")
print(data.columns)
# 访问特定字段的所有股票数据
print("\n所有股票的收盘价:")
print(data['Close'].head())
# 访问特定股票的所有数据
print("\nTSLA 的所有数据:")
print(data.xs('TSLA', level=1, axis=1).head()) # 使用 xs 进行跨层级选择
# 也可以设置 group_by='ticker' 使列索引先按 Ticker 分组
data_grouped_by_ticker = yf.download("NVDA TSLA NFLX", start="2024-01-01", end="2024-04-01", group_by='ticker')
print("\n按 Ticker 分组的数据 (部分):")
print(data_grouped_by_ticker.head())
print("\n按 Ticker 分组的列索引:")
print(data_grouped_by_ticker.columns)
print("\n访问 TSLA 的收盘价 (按 Ticker 分组):")
print(data_grouped_by_ticker['TSLA']['Close'].head())
yf.download() 是批量获取历史数据的推荐方式。
8. 高级技巧与注意事项
8.1 错误处理 (无效 Ticker)
当请求一个不存在或 Yahoo Finance 没有数据的 Ticker 时，yfinance 可能会抛出错误或返回空数据。在处理用户输入或大量 Ticker 列表时，进行错误处理很重要。
invalid_ticker_symbol = "INVALIDTICKERXYZ"
try:
invalid_ticker = yf.Ticker(invalid_ticker_symbol)
# 尝试获取数据，这通常会失败或返回空
info = invalid_ticker.info
hist = invalid_ticker.history(period="1d")
if not info and hist.empty:
print(f"\nTicker '{invalid_ticker_symbol}' 似乎无效或没有数据。")
# 注意：某些情况下 info 可能返回 {}，history 可能直接抛错，具体行为可能变化
except Exception as e:
print(f"\n处理 Ticker '{invalid_ticker_symbol}' 时发生错误: {e}")
# 对于 yf.download()，它通常会打印错误消息但继续下载其他有效的 Ticker
data = yf.download("AAPL INVALIDTICKERXYZ GOOG", period="1d")
print("\n尝试下载包含无效 Ticker 的数据:")
# 查看下载结果，INVALIDTICKERXYZ 的数据列通常会是 NaN
# print(data)
8.2 数据可视化 (简单示例)
获取的数据通常是 Pandas DataFrame，可以方便地使用 matplotlib 或 seaborn 进行可视化。
import matplotlib.pyplot as plt
# 获取微软过去一年的数据
msft_hist = msft.history(period="1y")
# 绘制收盘价曲线
plt.figure(figsize=(10, 5))
msft_hist['Close'].plot(title='Microsoft (MSFT) Stock Price (Last Year)')
plt.ylabel('Price (USD)')
plt.xlabel('Date')
plt.grid(True)
plt.show()
# 绘制成交量柱状图
plt.figure(figsize=(10, 3))
msft_hist['Volume'].plot(kind='bar', title='Microsoft (MSFT) Trading Volume (Last Year)')
plt.ylabel('Volume')
plt.xlabel('Date')
# 由于日期标签太多，可能需要调整显示方式，例如只显示部分标签或按月聚合
# plt.xticks(rotation=45) # 旋转标签
plt.show()
8.3 代理设置 (Proxy)
如果在网络受限的环境（如公司网络）或因请求频繁被暂时限制，可能需要设置代理。
# 示例：设置 HTTP 和 HTTPS 代理
# proxies = {
# 'http': 'http://user:password@proxy.server.com:port',
# 'https': 'https://user:password@proxy.server.com:port',
# }
# 在 Ticker 对象级别设置 (会话级别)
# msft = yf.Ticker("MSFT")
# msft.set_proxy(proxies)
# hist = msft.history(period="1d")
# 或者在 download 函数中设置
# data = yf.download("AAPL", period="1d", proxy=proxies)
# 注意：代理设置的 API 可能会随版本变化，请查阅最新文档。
# 较新版本倾向于使用 Session 对象进行更底层的控制，但这超出了基础教程范围。
print("\n代理设置: 请参考 yfinance 文档以获取最新和最可靠的代理设置方法。")
8.4 请求频率限制
Yahoo Finance 并未公开其确切的请求频率限制，但过于频繁的请求（尤其是在短时间内大量请求不同 Ticker 的多种数据）可能导致 IP 被暂时封禁（通常返回 HTTP 403 或 429 错误）。
- 策略:
- 尽量使用
Tickers对象或yf.download()进行批量操作，而不是在循环中单独请求每个 Ticker。 - 如果在循环中进行请求，请在每次请求后加入适当的延迟（例如
time.sleep(1)）。 - 避免不必要的数据请求。
- 如果需要大量数据，考虑分批次、在不同时间进行。
- 尽量使用
import time
tickers_to_fetch = ["AAPL", "MSFT", "GOOG", "AMZN", "META", "NVDA", "TSLA"] # 示例列表
all_info = {}
for symbol in tickers_to_fetch:
try:
print(f"正在获取 {symbol} 的信息...")
ticker = yf.Ticker(symbol)
all_info[symbol] = ticker.info
# 在每次请求后加入短暂延迟，避免过快请求
time.sleep(1) # 暂停 1 秒
except Exception as e:
print(f"获取 {symbol} 信息失败: {e}")
print("\n获取到的部分信息:")
# print(all_info.get("AAPL", {}).get("longName"))
# print(all_info.get("MSFT", {}).get("longName"))
9. 总结
yfinance 是一个功能强大且易于使用的 Python 库，用于从 Yahoo Finance 获取金融数据。本教程涵盖了其核心功能：
- 使用
Ticker对象获取单个金融工具的数据（info,history,financials,options,news等）。 - 使用
Tickers对象或yf.download()高效处理多个金融工具。 - 了解了数据的格式 (Pandas DataFrame/Series) 和一些常用参数。
- 讨论了错误处理、可视化基础以及请求频率等注意事项。
要进一步深入，建议：
- 阅读官方文档: 虽然
yfinance的文档可能不如一些大型库详尽，但仍然是获取最新信息的主要来源。 - 实践: 尝试获取不同类型 Ticker（股票、ETF、指数、加密货币等）的数据，探索不同的参数组合。
- 结合其他库: 将
yfinance获取的数据与pandas进行深入分析，与matplotlib/seaborn/plotly进行高级可视化，或与scikit-learn等库进行量化分析。
希望本教程能帮助你更好地理解和使用 yfinance 库！
扫一扫
49
被折叠的 条评论
为什么被折叠?
到【灌水乐园】发言
