Skip to main content

Download market data from Yahoo! Finance API

Project description

Download market data from Yahoo! Finance's API


Yahoo!, Y!Finance, and Yahoo! finance are registered trademarks of Yahoo, Inc.

yfinance is not affiliated, endorsed, or vetted by Yahoo, Inc. It's an open-source tool that uses Yahoo's publicly available APIs, and is intended for research and educational purposes.

You should refer to Yahoo!'s terms of use (here, here, and here) for details on your rights to use the actual data downloaded. Remember - the Yahoo! finance API is intended for personal use only.

Python version PyPi version PyPi status PyPi downloads Travis-CI build status CodeFactor Star this repo Follow me on twitter

yfinance offers a threaded and Pythonic way to download market data from Yahoo!Ⓡ finance.

→ Check out this Blog post for a detailed tutorial with code examples.

Changelog »


Install yfinance using pip:

$ pip install yfinance --upgrade --no-cache-dir

With Conda.

To install with optional dependencies, replace optional with: nospam for caching-requests, repair for price repair, or nospam,repair for both:

$ pip install "yfinance[optional]"

Required dependencies , all dependencies.

Quick Start

The Ticker module

The Ticker module, which allows you to access ticker data in a more Pythonic way:

import yfinance as yf

msft = yf.Ticker("MSFT")

# get all stock info

# get historical market data
hist = msft.history(period="1mo")

# show meta information about the history (requires history() to be called first)

# show actions (dividends, splits, capital gains)
msft.capital_gains  # only for mutual funds & etfs

# show share count
msft.get_shares_full(start="2022-01-01", end=None)

# show financials:
# - income statement
# - balance sheet
# - cash flow statement
# see `Ticker.get_income_stmt()` for more options

# show holders

# show recommendations

# Show future and historic earnings dates, returns at most next 4 quarters and last 8 quarters by default.
# Note: If more are needed use msft.get_earnings_dates(limit=XX) with increased limit argument.

# show ISIN code - *experimental*
# ISIN = International Securities Identification Number

# show options expirations

# show news

# get option chain for specific expiration
opt = msft.option_chain('YYYY-MM-DD')
# data available via: opt.calls, opt.puts

If you want to use a proxy server for downloading data, use:

import yfinance as yf

msft = yf.Ticker("MSFT")

msft.history(..., proxy="PROXY_SERVER")
msft.option_chain(..., proxy="PROXY_SERVER")

Multiple tickers

To initialize multiple Ticker objects, use

import yfinance as yf

tickers = yf.Tickers('msft aapl goog')

# access each ticker using (example)

To download price history into one table:

import yfinance as yf
data ="SPY AAPL", period="1mo") and Ticker.history() have many options for configuring fetching and processing. Review the Wiki for more options and detail.


yfinance now uses the logging module to handle messages, default behaviour is only print errors. If debugging, use yf.enable_debug_mode() to switch logging to debug with custom formatting.

Smarter scraping

Install the nospam packages for smarter scraping using pip (see Installation). These packages help cache calls such that Yahoo is not spammed with requests.

To use a custom requests session, pass a session= argument to the Ticker constructor. This allows for caching calls to the API as well as a custom way to modify requests via the User-agent header.

import requests_cache
session = requests_cache.CachedSession('yfinance.cache')
session.headers['User-agent'] = 'my-program/1.0'
ticker = yf.Ticker('msft', session=session)
# The scraped response will be stored in the cache

Combine requests_cache with rate-limiting to avoid triggering Yahoo's rate-limiter/blocker that can corrupt data.

from requests import Session
from requests_cache import CacheMixin, SQLiteCache
from requests_ratelimiter import LimiterMixin, MemoryQueueBucket
from pyrate_limiter import Duration, RequestRate, Limiter
class CachedLimiterSession(CacheMixin, LimiterMixin, Session):

session = CachedLimiterSession(
    limiter=Limiter(RequestRate(2, Duration.SECOND*5)),  # max 2 requests per 5 seconds

Managing Multi-Level Columns

The following answer on Stack Overflow is for How to deal with multi-level column names downloaded with yfinance?

  • yfinance returns a pandas.DataFrame with multi-level column names, with a level for the ticker and a level for the stock price data
    • The answer discusses:
      • How to correctly read the the multi-level columns after saving the dataframe to a csv with pandas.DataFrame.to_csv
      • How to download single or multiple tickers into a single dataframe with single level column names and a ticker column

Persistent cache store

To reduce Yahoo, yfinance store some data locally: timezones to localize dates, and cookie. Cache location is:

  • Windows = C:/Users/<USER>/AppData/Local/py-yfinance
  • Linux = /home/<USER>/.cache/py-yfinance
  • MacOS = /Users/<USER>/Library/Caches/py-yfinance

You can direct cache to use a different location with set_tz_cache_location():

import yfinance as yf

Developers: want to contribute?

yfinance relies on community to investigate bugs and contribute code. Developer guide:

Legal Stuff

yfinance is distributed under the Apache Software License. See the LICENSE.txt file in the release for details.

AGAIN - yfinance is not affiliated, endorsed, or vetted by Yahoo, Inc. It's an open-source tool that uses Yahoo's publicly available APIs, and is intended for research and educational purposes. You should refer to Yahoo!'s terms of use (here, here, and here) for details on your rights to use the actual data downloaded.


Please drop me an note with any feedback you have.

Ran Aroussi

Project details

Release history Release notifications | RSS feed

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

yfinance-0.2.40.tar.gz (84.2 kB view hashes)

Uploaded Source

Built Distribution

yfinance-0.2.40-py2.py3-none-any.whl (73.5 kB view hashes)

Uploaded Python 2 Python 3

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page