Screenipy screens NSE stocks for breakouts through a Streamlit GUI

What the screener actually looks for in NSE instruments

Screenipy is described as an advanced stock screener to find potential breakout stocks from NSE and to tell its possible breakout values. The description adds that it helps find stocks that are consolidating and may breakout, or the particular chart patterns a user is looking for specifically. That is the whole product in three claims: a universe of Indian NSE instruments, a set of technical conditions the user chooses, and an output that says where a breakout might occur. The documentation also states that Screenipy is totally customizable and can screen stocks with the settings you have provided, which is the difference between it and a fixed indicator script. The result table is where that shows up, since the project ships a parameter by parameter description of the output columns because the table contains a lot of different parameters that can be pretty overwhelming to new users. Where an OS or terminal supports unicode, a stock symbol in that table can be opened directly in TradingView charts with Ctrl+Click, which is a small decision that shortens the path from a screening result to the actual chart.

The CLI release is deprecated in favour of a GUI

The most consequential structural change in the project is that the older command line version is marked as deprecated, and the current recommended path is the GUI based version. The old flow, which the README still documents, involved downloading a file for your operating system or pulling a Docker image, making sure the screenipy.bin or screenipy.run file had execute permission on Linux and Mac, running the file, then configuring parameters through Option > 8. Results could be saved to an Excel file once a run finished. The newer flow replaces that menu driven console with a browser interface, and the project ships three video guides covering installation, configuration and usage, plus a separate one on how to install software updates. Keeping the old instructions in the repository is useful for anyone migrating, but a reader should treat the deprecated section as history rather than as the current interface.

The Docker path publishes 8501 and 8000 and checks its own health

The recommended route for the current version is to install Docker Desktop and pull the latest docker image from the release page, and the compose file in the repository shows how the container is wired. The service is built from the local Dockerfile, named screenipy, and maps two ports:

    container_name: screenipy
    ports:
      - "8501:8501"
      - "8000:8000"

The 8501 port is the Streamlit interface, and the healthcheck confirms it by hitting the Streamlit health endpoint:

    healthcheck:
      test: ["CMD", "curl", "--fail", "http://localhost:8501/_stcore/health"]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 40s

Three named volumes keep configuration, data and logs persistent across restarts, and the container is set to restart unless stopped. The environment section passes through SCREENIPY_API_KEY with a placeholder default and a PYTHONUNBUFFERED setting, so the compose file is meant to be edited before first use rather than run as shipped.

The dependency list mixes indicators, plotting, LLM clients and a vector store

The pyproject metadata lists a large dependency set, and reading it tells you what the application really is. The numeric core is numpy, scipy, pandas, ta-lib and ta, with mplfinance for the chart output and num2words for turning numbers into words. Market data comes from yfinance at a pinned 0.2.61, and nsetools is listed alongside it, which is how the Indian instrument universe is addressed. openpyxl is there for the Excel export. The newer additions are the interesting part: streamlit at 1.44.1 with streamlit-local-storage for the GUI, openai-agents, anthropic and litellm for model access, chromadb at 1.0.0 as a vector store, apscheduler for scheduling, plotly for interactive charts, and httpx. The Python requirement is where to look before anything else:

requires-python = ">=3.13,<3.14"

That range admits one minor version. It is a narrow pin, and it means a workstation running 3.12 or 3.14 cannot install the project as published.

The container image patches a broken NumPy call in a third party indicator

The Dockerfile reveals a specific compatibility problem the project has to work around. The image is based on python:3.13-slim-bookworm, and the build copies uv from the ghcr.io/astral-sh/uv image to install dependencies. The comment in the file explains that advanced-ta is installed with --no-deps to bypass its numpy<2.0.0 constraint, and that one broken call site has to be fixed because np.NaN was removed in NumPy 2.0. The patch is applied by a python heredoc inside the build that locates a Classifier.py under the venv and rewrites it. A second install step pulls advanced-ta and pandas-ta-remake with --no-deps, and streamlit-local-storage is installed separately with a version constraint. This is worth reading before anyone rebuilds the image, because it means the container is not a plain dependency install and the patched library version can drift out of step with upstream fixes.

Maintenance is current but the release stream is thin

The repository is not archived and the last push was on 2026-09-07, so the code is being worked on. The tagged releases are fewer: v3.0.2 on 2026-06-01, v3.0.1 on 2026-06-01 and 2.29 on 2025-07-25. The project version in the packaging metadata matches the newest tag at 3.0.2, which means the published package corresponds to the current tree rather than trailing it. The licence is MIT, which is permissive and imposes no copyleft obligation on anything you build with it. The repository layout shows the operational pieces in the open: a Dockerfile, a docker-compose.yml, a Makefile, an INSTALLATION.md, a CONTEXT.md and a CONTRIBUTING.md, plus a run_screenipy.sh launcher, a screenipy.yaml configuration file, a patterns directory, an actions-data-download directory, src/, test/ and a uv.lock file. The lock file and the pyproject based build mean a reproducible install is possible, which is what you want when the dependency set is this wide.

Screenipy finds candidates, it does not tell you what happened next

The honest limitation is what the output does not contain. A breakout value is a computed level derived from current price action, not a validated expectation, and nothing in the documentation describes a backtest, a hit rate or a track record for the screening rules. So the tool answers which instruments currently match a condition, which is useful, but it does not answer whether acting on that condition would have paid. There is a second limitation in the data path: market data arrives through yfinance, and the screen is therefore limited to what that source provides for NSE symbols, with nsetools handling instrument metadata. A screening run is a point-in-time read of that data, and the project has no documented behaviour for stale or missing quotes. A third constraint is the LLM configuration. The compose file expects SCREENIPY_API_KEY and comments out LLM_PROVIDER, LLM_MODEL and LLM_BASE_URL for non-OpenAI providers, so a deployment that leaves the placeholder default is running with an API key that is not real. And with the CLI deprecated, a headless workflow now depends on the web interface, which is a change in how you would schedule and script runs.

Where Screenipy is the wrong tool

Three situations call for something else. The first is a backtesting workflow, where a framework that replays history through a strategy and reports equity curves is needed rather than a screener that prints a table of current matches. The second is a multi-market user, because the universe here is explicitly NSE and the symbol handling, exchange specific session logic and corporate action quirks of other markets are not part of this tool. The third is a server deployment with an API contract, since the current release is a Streamlit application designed to be opened in a browser, and the older CLI that could be scripted and cron driven is marked deprecated. There is also a dependency-heavy risk that deserves a mention: the pinned ta-lib and scipy versions, the NumPy 2 patch to advanced-ta and the Python 3.13 only range mean that rebuilding this on another machine or another Python version is a real piece of work rather than a routine install. For an analyst who wants to look at a list of NSE instruments matching a pattern today, that cost is worth paying. For anything load-bearing, it deserves a second look first.

Editorial conclusion

Adopt Screenipy if you want a configurable NSE screener that runs on your own machine and hands you a result table and an Excel export, and steer clear if you need tested backtest results or a multi-exchange screener, because nothing in the documentation claims either. Verify first that you are on Python 3.13 exactly, since the project metadata pins the range to >=3.13,<3.14, and read INSTALLATION.md before deploying the container, where the compose file expects SCREENIPY_API_KEY and exposes ports 8501 and 8000.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. pranjal-joshi/Screeni-py on GitHub
4. README
5. Releases