yfinance

yfinance is a Python library that downloads historical and near-real-time market data from Yahoo! Finance’s public API and shapes it into pandas DataFrames and Series so it drops straight into an existing analysis or backtesting pipeline. A single Ticker object exposes prices, dividends/splits, options chains, financial statements, holders, recommendations, and company metadata, while Tickers and the module-level download() function batch the same calls across many symbols concurrently.

Beyond single-symbol lookups, the library also wraps Yahoo’s sector/industry classification data, an equity/fund screener with predefined and custom EquityQuery/FundQuery filters, ticker search and symbol lookup, and both synchronous and asyncio-based WebSocket clients for streaming live quotes. It is explicitly research/education-oriented — it scrapes a public, undocumented API rather than a licensed data feed, so it favors resilience (retries, caching, rate-limit handling) over guaranteed uptime.

What You Get

• Ticker/Tickers objects exposing history, dividends, splits, options chains, financial statements, holders, and recommendations as pandas objects
• Module-level download() for concurrent multi-symbol OHLCV history downloads with threading via multitasking
• Search, Lookup, Sector, Industry, and Market helpers for discovery and classification data
• EquityQuery/FundQuery/ETFQuery and screen() for building and running Yahoo’s stock/fund screener, including predefined query presets
• Synchronous WebSocket and AsyncWebSocket clients for streaming live price updates over protobuf-encoded messages
• Built-in HTTP session handling with retry/backoff for transient errors, optional curl_cffi browser impersonation, and a local timezone/response cache via peewee/SQLite

Common Use Cases

• Backtesting trading strategies against historical OHLCV, split, and dividend data pulled straight into pandas
• Building a personal portfolio tracker or dashboard that needs live-ish quotes, fundamentals, and holder/institutional-ownership data
• Screening stocks or funds by custom criteria (sector, valuation, performance) using the built-in screener query builder
• Academic or personal research projects that need free, no-signup access to market data for a handful to a few hundred tickers
• Streaming live price ticks into a lightweight monitoring script via the WebSocket client

Under The Hood

Architecture - The library is organized around a TickerBase class (yfinance/base.py, ~830 lines) that Ticker (yfinance/ticker.py) subclasses; TickerBase lazily fetches and caches sub-resources (price history, options, fundamentals) by delegating to focused scraper modules under yfinance/scrapers/ (history.py, fundamentals.py, holders.py, quote.py, analysis.py, funds.py) and domain objects under yfinance/domain/ (sector.py, industry.py, market.py). All HTTP access is centralized through a shared YfData class in data.py, which every scraper calls rather than issuing requests directly, giving the library one place to apply retries, rate-limit backoff, and cookie/crumb-based auth against Yahoo’s undocumented endpoints. multi.py implements the batch download() entry point using the multitasking library to fan requests out across threads, and live.py implements the WebSocket streaming clients on top of protobuf messages defined in pricing.proto/pricing_pb2.py.

Tech Stack - Pure Python 3.6+ targeting pandas (>=1.3.0) and numpy for data shaping, requests plus curl_cffi (for TLS/browser fingerprint impersonation, since Yahoo blocks generic bot traffic) for HTTP, beautifulsoup4 for the small amount of HTML scraping still needed, peewee for a local SQLite-backed timezone/response cache, protobuf and websockets for the live-streaming feature, and platformdirs/pytz for cross-platform cache paths and timezone handling. No async framework is used outside the dedicated AsyncWebSocket client; the rest of the library is synchronous with thread-based concurrency for batch downloads.

Code Quality - The tests/ directory has 249 test functions spread across 19 files (test_ticker.py, test_prices.py, test_download_concurrency.py, test_screener.py, test_live.py, test_cache.py, etc.), covering price history edge cases, price-repair heuristics, screener queries, caching under restricted permissions, and locale handling — run via unittest with a shared tests/context.py fixture. A dedicated exceptions.py module defines a small hierarchy (YFException -> YFTickerMissingError -> YFTzMissingError/YFPricesMissingError, plus YFNotImplementedError, YFRateLimitError) so callers can catch specific failure modes like delisted tickers or missing timezones rather than bare exceptions. A _is_transient_error() helper in data.py explicitly distinguishes retryable network failures from permanent ones, and a pyrightconfig.json plus type hints in newer modules (e.g. config.py) show incremental movement toward static typing in an otherwise loosely-typed, scraping-oriented codebase.

API Design - The public surface is intentionally small and pandas-native: yf.Ticker("AAPL").history(), .info, .options, .financials read like attribute access on a familiar object rather than a bespoke client API, and yf.download(["AAPL", "MSFT"]) mirrors pandas.read_csv-style ergonomics for the common batch case. Configuration is centralized in a single YfConfig singleton (config.py) covering network/proxy/retry/cache settings, replacing an older pattern of scattered keyword arguments (with set_config() kept only as a deprecated shim). Getting first output requires zero configuration (pip install yfinance then two lines of code), though deeper look-ups (screener queries, sector/industry taxonomies, WebSocket auth) require reading the docs to discover the right helper class.