finvizfinance turns the FinViz site into pandas dataframes

A scraper with a friendly surface

finvizfinance is a package which collects financial information from the FinViz website. The description in the project documentation is direct, and the repository is a single Python package with a small set of well named submodules.

The data it provides is listed by category. Stock charts, fundamental and technical information, insider information and stock news, then forex charts and performance, and crypto charts and performance. The screener and group classes provide dataframes for comparing stocks according to different filters and trading signals.

The implementation approach is visible in the dependency list, which is short and tells you what is happening under the hood. It is `pandas` for the dataframes, `requests` for the HTTP requests, `beautifulsoup4` and `lxml` for parsing the HTML, and `xlsxwriter` for writing spreadsheets. So it is a conventional requests and BeautifulSoup scraper with a tidy typed surface, not a data feed.

The install is either from PyPI or from a clone.

$ pip install finvizfinance

The project requires Python 3.10 or newer and supports up to 3.13, and the package is built with hatchling with the version read from `finvizfinance/__init__.py`. The documentation is on Read the Docs, and the classifiers describe it as Development Status 5, Production/Stable.

The audience is a retail or independent analyst working in Python, someone who wants a screener result or a fundamentals table in a notebook rather than a page of HTML.

The licence is MIT, and the author is Tianning Li.

Quote is the entry point for one ticker

The `quote` submodule is where most usage starts. You construct a `finvizfinance` object with a ticker symbol, and every method on it is one kind of information about that company.

from finvizfinance.quote import finvizfinance

stock = finvizfinance('tsla')

The methods map onto the data categories. `ticker_charts()` returns chart data, `ticker_fundament()` returns the fundamentals as a dictionary, and the example in the documentation shows the shape of that dictionary, with keys like Company, Sector, Industry, Country, P/E, EPS (ttm), Insider Own, Shs Outstand, Perf Week, Market Cap and Forward P/E.

`ticker_description()` returns the business description as a string. `ticker_peer()` returns the list of peer tickers, the example showing a list of ten. `ticker_etf_holders()` returns the ETFs holding the stock, again a list of ten.

Three of the methods return dataframes rather than dictionaries or lists, and those are the ones that need the most parsing. `ticker_outer_ratings()` gives the aggregate ratings from other sites, `ticker_news()` gives the news table, and `ticker_inside_trader()` gives the insider trading table. The documentation pairs each of them with a screenshot in the `asset/` directory, which is a quick way to see the shape of each frame without running anything.

The point of the design is that a caller does not have to know anything about FinViz's HTML structure. You call a method named after the data you want and you get a dictionary or a dataframe. The cost of that convenience is that the same abstraction hides the fact that every one of these calls is a fresh request to a website.

Screeners, the economic calendar and earnings partitioning

Three features go beyond a single ticker and are the reason someone would take a dependency on this package.

The screener classes take a dictionary of filters and return a dataframe of matching tickers. The documented example uses the Overview screener with a filter on Index and Sector.

from finvizfinance.screener.overview import Overview

foverview = Overview()
filters_dict = {'Index':'S&P 500','Sector':'Basic Materials'}
foverview.set_filter(filters_dict=filters_dict)
df = foverview.screener_view()
df.head()

The screener categories are named in the documentation as Overview, Valuation, Financial, Ownership, Performance and Technical, and there is a separate Ticker screener that returns the list of tickers matching the filters rather than a full table.

The economic calendar returns release datetime, impact, and the actual, expected and prior values.

from finvizfinance.calendar import Calendar

fcalendar = Calendar()
df = fcalendar.calendar()

The earnings module partitions tickers by their earnings date over a period, with the period options being This Week as the default, Next Week, Previous Week and This Month, and a mode that selects which set of fields to return, financial as the default, or overview, valuation, ownership, performance or technical. It can also export the partitioned tables directly to a spreadsheet or a CSV.

from finvizfinance.earnings import Earnings

fearnings = Earnings(period='This Week')
days = fearnings.partition_days(mode='financial')
fearnings.output_excel('earning_days.xlsx')

Two more modules round it out. `News` returns recent financial news split into news and blogs, and `Insider` returns insider trading information with the option of latest, top week or top owner trade.

The forex, crypto and futures modules follow the same pattern, and the futures one takes a timeframe of D as the default, W, M, Q, HY or Y.

Proxy support exists because the requests go out to a website

There is one small feature in the package that tells you more about its nature than any of the data methods.

The misc module offers an optional proxy for getting information from the FinViz website, accessible from finvizfinance, and it is described as an extension of the requests library proxies.

from finvizfinance.util import set_proxy

proxies={'http': 'http://127.0.0.1:8080'}
set_proxy(proxies)

A proxy helper is not a feature you need in a library that consumes an official API, because the API endpoint is fixed and reachable. It is a feature you need when the target is a website, because websites are frequently blocked by corporate networks, by regional blocking, or by the sort of filtering a residential proxy is used to work around.

That single function is a good summary of the project. Every method is an HTTP request to a page on a site that was designed for a human to read, parsed with BeautifulSoup and lxml, and returned as a pandas object. It is a very good citizen of that approach: the parsing is behind named methods, the results are dataframes, the proxy case is handled, and there is an optional extension mechanism for anything the package does not cover.

The repository layout matches. There is a `finvizfinance/` package directory, an `asset/` directory with the example screenshots, an `example/` directory with a Jupyter notebook and sample chart images for equities, forex and crypto, a `docs/` directory for the Read the Docs build, a `test/` directory, a `pytest.ini` for the test configuration, and a `release.md` for the release process.

Two releases in a row about reliability

The release history says something about where the project's effort has gone.

Version 1.4.0 was published on 2026-08-27 and titled as a reliability overhaul. Version 1.5.0 followed on 2026-08-29, two days later, titled as modernization and reliability. Before that, version 1.3.0 came on 2026-01-03. The last push to the repository was on 2026-08-29, the same day as the 1.5.0 tag.

Two releases in two days, both framed around reliability, is the signature of a project whose main risk is not a broken feature but a broken selector. When you parse a website, the work is not writing the parser, it is surviving the site changing its markup, and every version bump is really a statement about which parts of the page have moved.

The tooling around that is worth noting too. The project uses `ruff` for linting, `mypy` for type checking, `pre-commit` for hooks, `pytest` with `pytest-mock` for the tests, `coverage` for reporting, and Sphinx with the read the docs theme for the documentation build, and it is all configured in the `pyproject.toml` with optional dependency groups for `test`, `docs` and `dev`.

For a user, that combination says two things. The typing and linting discipline is a sign that the return types of these methods are meant to be relied on, which matters if you are putting the dataframes into a pipeline. And the recent release cadence says the maintainer is still chasing the upstream site, which is exactly what you want from a scraper and exactly what you do not want to depend on for a system that has to be correct.

The project also keeps a code of conduct and a contributing guide, and it takes donations through PayPal, which is the usual arrangement for a small library that a lot of people use and few people maintain.

Where a web scraper is the wrong tool

The limitations are structural and worth being blunt about, because the package is pleasant to use and easy to misuse.

The first is that there is no data guarantee. The values are whatever the page says today, they are not versioned, and there is no way to ask the package what a value was last quarter. For a chart of a stock's price history that is fine. For a backtest, a risk report, or anything that has to be reproducible, a package that reads the current page is the wrong instrument, because the input changes underneath you.

The second is the request pattern. Every method is a separate HTTP request to a site that is not yours, and the screener classes are the worst case, since a filter over a large universe is a wide request. Run that on a schedule and you are a load on somebody's free website, and FinViz's own terms are not something the package can grant you.

The third is that the package is a best-effort reader of a page rather than a supported data contract, so how far you can rely on it depends entirely on the maintainer keeping up with the site.

So the honest use case is the exploratory one. A notebook where you want to see the fundamentals table for a list of tickers, a screener result to paste into a chart, a quick look at insider transactions before a meeting, or a prototype of an idea where the data source will be replaced with something proper later. For any of those, the package is a good fit, and the reliability work in the recent releases is what makes it usable.

For anything that runs unattended against a schedule and feeds a decision, the scrape is the wrong foundation, and the fix is a data feed rather than a different scraping library.

Editorial conclusion

finvizfinance suits a Python analyst who wants FinViz's fundamentals, screeners and insider tables in a notebook or a script without writing the scraping code, and who accepts that the data is a snapshot of a website rather than a feed. It is the wrong tool for a production risk system or a backtest that needs point-in-time data, since the site serves current values only. Check first how you intend to use it, because the package performs a request per call and a screen over a large universe will hammer the site, and read the proxy section if you are behind a corporate network.

Frequently asked questions

Official sources

1. License: MIT
2. lit26/finvizfinance on GitHub
3. Project website
4. README
5. Releases