Migrate from yfinance

yfin is designed so most yfinance-shaped Python code can keep the same call patterns. The usual migration is changing the import and, for services or agents, declaring a contact identity.

Minimal Migration

Before:

import yfinance as yf

ticker = yf.Ticker("AAPL")
history = ticker.history(period="5d", interval="1d")

After:

import yfin as yf

ticker = yf.Ticker("AAPL", contact="you@example.com")
history = ticker.history(period="5d", interval="1d")

For larger codebases, keep the alias as yf and replace the package import:

- import yfinance as yf
+ import yfin as yf

You can also set identity once for a process:

export YFIN_CONTACT=you@example.com

Compatibility Map

Use this table to migrate common yfinance calls. The right column shows what to change when moving to yfin.

Existing yfinance usage	yfin usage	Migration notes
import yfinance as yf	import yfin as yf	Keep the yf alias so most existing code does not change.
yf.Ticker("AAPL")	yf.Ticker("AAPL")	Optionally pass contact="you@example.com" or set YFIN_CONTACT.
ticker.history(period="1mo", interval="1d")	Same call	Supports period, start, end, interval, prepost, actions, auto_adjust, back_adjust, keepna, and rounding.
yf.download(["AAPL", "MSFT"], period="5d")	Same call	Works for one ticker or many tickers.
ticker.fast_info	Same property	Returns a dict-like fast quote snapshot.
ticker.info	Same property	Returns a dict suitable for existing ticker.info[...] access patterns.
ticker.history_metadata	Same property	Returns chart metadata for the ticker.
ticker.options	Same property	Returns available option expiration dates.
ticker.option_chain()	Same call	Accepts an optional expiration date, same as yfinance-style usage.
ticker.dividends	Same property	Returns a pandas Series.
ticker.splits	Same property	Returns a pandas Series.
ticker.actions	Same property	Returns dividends, splits, and capital gains where Yahoo returns them.
ticker.capital_gains	Same property	Returns a pandas Series where Yahoo returns fund capital gains.
ticker.financials, ticker.income_stmt	Same properties	Returns pandas DataFrames.
ticker.balance_sheet	Same property	Returns a pandas DataFrame.
ticker.cash_flow	Same property	Returns a pandas DataFrame.
ticker.quarterly_income_stmt	Same property	Quarterly financial statement access keeps the yfinance-shaped property name.
ticker.ttm_income_stmt, ticker.ttm_cash_flow	Same properties	Trailing-twelve-month statement access keeps the yfinance-shaped property names.
ticker.earnings, ticker.earnings_dates	Same properties/calls	get_earnings_dates(limit=..., offset=...) is also available.
ticker.recommendations	Same property	Returns analyst recommendation trend data as a DataFrame.
ticker.upgrades_downgrades	Same property	Returns analyst upgrade/downgrade history as a DataFrame.
ticker.analyst_price_targets	Same property	Returns target price fields in a dict.
ticker.major_holders	Same property	Returns holder data as a DataFrame.
ticker.institutional_holders	Same property	Returns holder data as a DataFrame.
ticker.mutualfund_holders	Same property	Returns holder data as a DataFrame.
ticker.insider_transactions	Same property	Returns insider transaction data as a DataFrame.
ticker.calendar	Same property	Returns earnings and calendar event data as a dict.
ticker.sec_filings	Same property	Returns SEC filing metadata as a dict.
ticker.sustainability	Same property	Returns ESG/sustainability data where Yahoo returns it.
ticker.shares, ticker.shares_full	Same properties/calls	get_shares_full(start=..., end=...) is also available.
ticker.funds_data.top_holdings	Same property path	Fund overview, operations, holdings, ratings, and sector weightings keep the yfinance-shaped access pattern.
ticker.news	Same property	Returns a list of article dictionaries.
yf.WebSocket(...), yf.AsyncWebSocket(...)	Same constructors	Subscribe to symbols using the same high-level shape.

Migration Checklist

1. Install yfin:

pip install yfin

2. Replace the import:

import yfin as yf

3. Add a contact identity for scripts, services, notebooks, and agents:

export YFIN_CONTACT=you@example.com

4. Run your existing yfinance tests or notebook cells.

5. If you hit rate limits, check Rate Limits and use an API key when your workload needs higher limits.

Useful yfin Additions

These are not required for migration, but they are useful once existing code is running on yfin.

Use the low-level hosted API client:

import yfin

client = yfin.Client(contact="you@example.com")
print(client.quote(["AAPL", "MSFT"]))
print(client.history("NVDA", range="5d", interval="1h"))

Access an advanced endpoint by catalog ID:

import yfin as yf

ticker = yf.Ticker("AAPL")
payload = ticker.raw("v7.quote", symbols="AAPL,MSFT")

Browse REST endpoints in the API Reference.

What Changes

• yfin uses the hosted api.yfin.dev API, so the same market-data surface is available from Python, REST, TypeScript, JavaScript, and AI tools.
• Public usage works without signup, but services should declare YFIN_CONTACT or pass contact=.
• Existing yfinance-shaped calls are the migration target. Code that imports private yfinance modules should use yfin's public SDK or REST API instead.