yfinance: a Python wrapper over Yahoo Finance, and the legal line it sits on

One pip install over Yahoo's public endpoints

The install is one line, which is a fair summary of the whole project:

pip install yfinance

There is a second path worth knowing about. The README points to an Advanced installation page for installing without `curl_cffi` as the requests fallback, which tells you that the library ships a browser-impersonating HTTP client by default rather than relying on plain `requests`.

That single dependency explains most of what makes this library work and most of what makes it fragile. `pyproject.toml` requires `curl_cffi>=0.15`, alongside `pandas>=1.3.0`, `numpy>=1.16.5`, `peewee>=3.16.2`, `beautifulsoup4`, `lxml`, `multitasking`, `platformdirs`, `protobuf`, `pytz`, `requests>=2.31` and `websockets>=13.0`. The `peewee` dependency is notable: a SQLite ORM in a market data library is there because the project caches responses locally rather than hammering the upstream endpoint on every call.

The declared support is broad. Classifiers list Python 3.6 through 3.13, the project status is Beta, and the build backend is setuptools with a dynamic version. There is a separate `repair` extra pulling in `scipy>=1.6.3` and `scikit-learn>=1.0`, which lines up with the price repair work that appears repeatedly in the release notes.

Ticker, Tickers, download and EquityQuery cover different jobs

The README names nine components, and the grouping is informative. `Ticker` handles a single symbol, `Tickers` handles several, and `download` covers bulk price history. Around those sit `Market` for market-level information, `Search` for quotes and news, `Sector` and `Industry` for classification data, and `WebSocket` plus `AsyncWebSocket` for live streaming.

The two names that tell you where this library has moved are `EquityQuery` and `Screener`. A screen query is a different product from a price history call: it lets you filter a universe by fundamentals and metadata and return matches, which is the sort of thing people used to hand-write SQL for. The 1.6.0 release notes mention a few new fields added to the Balance Sheet and Screener, so that surface is actively changing.

The live streaming piece is worth separating from the rest, because it is the part with the least room to absorb upstream changes. `websockets>=13.0` is in the dependency list, and the AsyncWebSocket class exists to consume a push feed rather than poll. If your use case needs intraday ticks rather than daily bars, that is a different reliability conversation from the one the rest of the library has.

Nothing in the README shows a usage example. The documented API lives on the documentation site at ranaroussi.github.io/yfinance, which the README announces prominently as the new documentation website. So the README tells you what exists and the docs site tells you how to call it.

Release notes as a map of what Yahoo keeps changing

Three releases in the repository's recent history describe the maintenance pattern better than any statement of intent could. Version 1.5.2, published 2026-07-23, has a one-line description: fix yfinance breaking with `curl_cffi>=0.16`. That is a dependency's breaking change reaching the library, and it was patched within weeks.

Version 1.6.0 followed on 2026-08-13 with price repair improvements, a few new fields on the balance sheet and screener, and what the notes call many little fixes. Version 1.7.0 came on 2026-08-26, where `history_metadata` starts lazy-loading `tradingPeriods`, alongside proxy fixes and stock-split price repair. Credit is given to individual contributors in each entry, which is a sign of an active outside contribution flow rather than a single maintainer grinding alone.

Read together, those notes describe a project whose centre of gravity is repair rather than feature. Price repair is the recurring theme, which in context means correcting historical prices for splits and other corporate actions that Yahoo's raw series gets wrong. That is a genuinely valuable service and also an admission about the underlying data.

The repository carries both `CHANGELOG.md` and `CHANGELOG.rst`, a `meta.yaml` for conda-forge packaging, `ruff.toml` for formatting, a `tests/` directory and a `CONTRIBUTING.md`. The last push on the repository was on 2026-09-17, which is recent enough that breakages are being fixed as they appear.

Apache-2.0 covers the library, not the data it hands back

The README is unusually direct about this, and the directness is a reason to trust the rest of the project. Yahoo, Y!Finance and Yahoo! finance are registered trademarks of Yahoo, Inc. yfinance is not affiliated with, endorsed by, or vetted by Yahoo. It is described as an open source tool using Yahoo's publicly available APIs, intended for research and educational purposes. The README repeats the legal paragraph twice, once as an important notice near the top and once in a Legal Stuff section, and it links three separate Yahoo terms pages for your rights to use the actual downloaded data.

The last line of that notice is the one to remember: the Yahoo Finance API is intended for personal use only. So there are two licences in play and they do not cover the same thing. The library itself is Apache Software License 2.0, declared in `pyproject.toml` as a text licence and shipped as `LICENSE.txt`. The data comes from Yahoo under Yahoo's terms. An Apache-2.0 grant on your client code does not extend to the rows you retrieved with it.

That distinction decides where yfinance belongs. Personal research, an academic notebook, a personal portfolio tracker and a look at your own holdings all sit inside the stated intent. Anything that resells the data, feeds a product's backend, or serves derived values to third parties needs a different arrangement, and the README sends you to Yahoo rather than pretending the question is settled by the open source licence.

The project is also candid that it depends on the community for bug investigation and contribution, with a CONTRIBUTING.md linked directly from the README. That is reasonable for a project reverse-engineering an unofficial interface.

Where yfinance beats the alternatives and where it loses

The obvious comparison is with a paid market data vendor, and on that axis yfinance wins on price and loses on everything else. A licensed feed gives you a contract, a support address and a defined service level. yfinance gives you free access to whatever Yahoo currently serves through endpoints that were never documented as a public API for this purpose. The repair work in the release notes is the clearest evidence of that difference in kind.

The other comparison is with other unofficial wrappers, and here the differentiators are ordinary engineering ones. The `curl_cffi` default means requests look like browser traffic rather than a bare `requests` call. The `peewee` dependency means responses are cached rather than refetched. The docs are a real Sphinx site rather than a README. Optional `repair` extras with scikit-learn mean the split-adjustment logic is a separate concern you can leave out.

Against pandas-datareader, the old answer to the same question, yfinance has the advantage of being maintained by its own author and being the documented successor in practice, plus features datareader never had such as the screener and websocket clients.

The place it loses hardest is anything time-sensitive and unattended. A scheduled job that depends on today's yfinance working is depending on an undocumented endpoint staying reachable and staying shaped. For a research script that is a fair trade. For a trading system or a production dashboard, the mismatch between the two risk profiles is the whole argument.

Editorial conclusion

yfinance is the pragmatic choice for research, notebooks and personal portfolio tooling, because nothing else gives you Yahoo's data in pandas form with this little code. Treat it as a wrapper over someone else's private API rather than as a data provider with a contract, and the release history explains why: 1.5.2 exists only to repair breakage caused by a `curl_cffi` upgrade, and 1.7.0 is mostly price repair and lazy loading. Before you build anything commercial on it, read Yahoo's API terms yourself, because the Apache-2.0 licence covers the library and not the data it returns. Start with `yf.download` for a price history and move to `Ticker` and `EquityQuery` only when you need the deeper fields.

Frequently asked questions

Official sources

1. License: Apache-2.0
2. Project website
3. ranaroussi/yfinance on GitHub
4. README
5. Releases