Description

Download market data from Yahoo! Finance's API

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 »

Installation

Install yfinance using pip:

With Conda.

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

Required dependencies , all dependencies.

Quick Start

The Ticker module

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

For tickers that are ETFs/Mutual Funds, Ticker.funds_data provides access to fund related data.

Funds' Top Holdings and other data with category average is returned as pd.DataFrame.

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

Multiple tickers

To initialize multiple Ticker objects, use

To download price history into one table:

`yf.download()` and `Ticker.history()` have many options for configuring fetching and processing. Review the Wiki for more options and detail.

Sector and Industry

The Sector and Industry modules allow you to access the US market information.

To initialize, use the relevant sector or industry key as below. (Complete mapping of the keys is available in const.py.)

The modules can be chained with Ticker as below.

Market Screener

The Screener module allows you to screen the market based on specified queries.

Query Construction

To create a query, you can use the EquityQuery class to construct your filters step by step. The queries support operators: GT (greater than), LT (less than), BTWN (between), EQ (equals), and logical operators AND and OR for combining multiple conditions.

Screener

The Screener class is used to execute the queries and return the filtered results. You can set a custom body for the screener or use predefined configurations.

Logging

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.

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

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//AppData/Local/py-yfinance
Linux = /home//.cache/py-yfinance
MacOS = /Users//Library/Caches/py-yfinance

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

Developers: want to contribute?

yfinance relies on community to investigate bugs and contribute code. Developer guide: https://github.com/ranaroussi/yfinance/discussions/1084

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.