Python中的yfinance库深度解析与实战教程

---

yfinance 深度解析教程 (Python)

yfinance 是一个非常流行的 Python 库，允许用户从 Yahoo Finance 下载金融市场数据。它提供了一种简单方便的方式来获取股票价格、历史数据、基本面信息、期权数据等。本教程将深入探讨 yfinance 的核心功能和高级用法。

---

目录

1. 简介与安装
2. 1.1 什么是 yfinance?
3. 1.2 为什么选择 yfinance?
4. 1.3 安装 yfinance
5. 核心对象：Ticker
6. 2.1 创建 Ticker 对象
7. 2.2 获取股票信息 (info)
8. 获取历史市场数据 (history)
9. 3.1 基本用法 (周期 period)
10. 3.2 指定时间范围 (start, end)
11. 3.3 不同时间间隔 (interval)
12. 3.4 数据格式 (Pandas DataFrame)
13. 3.5 其他参数 (如 actions)
14. 获取基本面数据
15. 4.1 财务报表 (financials, balance_sheet, cashflow)
16. 4.2 盈利 (earnings)
17. 4.3 季度数据
18. 获取其他关键数据
19. 5.1 股票行为 (actions, dividends, splits)
20. 5.2 持股信息 (major_holders, institutional_holders)
21. 5.3 推荐评级 (recommendations)
22. 5.4 公司日历与盈利日期 (calendar, earnings_dates)
23. 5.5 ISIN 代码 (isin)
24. 5.6 相关新闻 (news)
25. 获取期权数据
26. 6.1 获取期权到期日 (options)
27. 6.2 获取特定到期日的期权链 (option_chain)
28. 处理多个 Ticker (Tickers)
29. 7.1 创建 Tickers 对象
30. 7.2 批量下载历史数据
31. 7.3 访问单个 Ticker 数据
32. 7.4 使用 yf.download() 批量下载
33. 高级技巧与注意事项
34. 8.1 错误处理 (无效 Ticker)
35. 8.2 数据可视化 (简单示例)
36. 8.3 代理设置 (Proxy)
37. 8.4 请求频率限制
38. 总结

---

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 库！

作者：hiquant