yfinance
Unofficial Python library that reverse-engineers Yahoo Finance's web API to download historical stock prices, dividends, splits, financial statements, and options data for free without an official API key.
Score Breakdown
⚙ Agent Friendliness
🔒 Security
All requests go to Yahoo Finance servers over HTTPS; no credentials handled; dependency on undocumented third-party API is a reliability and security concern
⚡ Reliability
Best When
You need free historical market data for personal projects, research, backtesting, or prototyping and can tolerate occasional breakage when Yahoo Finance changes its undocumented API.
Avoid When
Your application requires guaranteed uptime, licensed financial data, real-time tick data, or operates in a regulated environment where data source documentation is required.
Use Cases
- • Downloading historical OHLCV price data for a stock ticker over a date range into a pandas DataFrame for backtesting
- • Fetching quarterly income statements, balance sheets, and cash flow statements for fundamental analysis
- • Retrieving dividend and stock split history for total return calculations
- • Getting real-time or near-real-time quotes and market metadata (market cap, P/E ratio, sector) for screening
- • Downloading multiple tickers at once with yf.download(['AAPL', 'MSFT', 'GOOG'], start=, end=) for portfolio analysis
Not For
- • Production financial systems requiring guaranteed data reliability and SLA — this is an unofficial, reverse-engineered library
- • High-frequency trading or tick-level data — Yahoo Finance does not provide sub-minute resolution
- • Regulated financial applications where data provenance and licensing must be documented
Interface
Authentication
No authentication required for most endpoints; Yahoo Finance may rate-limit or block IPs with high request volume
Pricing
Apache 2.0 license for the library itself; data is sourced from Yahoo Finance — check Yahoo's terms of service for commercial use; library may break without notice when Yahoo changes their undocumented API
Agent Metadata
Known Gotchas
- ⚠ CRITICAL: This is an unofficial reverse-engineered library — Yahoo Finance periodically changes their undocumented API, breaking yfinance silently; always pin to a tested version and monitor for upstream breakage
- ⚠ Invalid or delisted tickers return an empty DataFrame or a Ticker object with None fields rather than raising an exception — agents must check if the result is empty before using it
- ⚠ Rate limiting from Yahoo Finance results in empty DataFrames or HTTP 429 errors that surface as exceptions inconsistently — add retry logic with exponential backoff for bulk downloads
- ⚠ Timezone handling in returned DatetimeIndex can vary by data type — price data is often in the exchange's local timezone, not UTC; always normalize to UTC before comparisons
- ⚠ Financial statement data (income_stmt, balance_sheet) field names and availability differ by company and reporting period — do not assume a specific column always exists
Alternatives
Full Evaluation Report
Detailed scoring breakdown, competitive positioning, security analysis, and improvement recommendations for yfinance.
Scores are editorial opinions as of 2026-03-06.