nselib Cheat Sheet

01Setup & importget going

$ pip install nselib★ START
From PyPI, Apache-2.0. Pulls pandas + requests. Tested on Python 3.8+.
$ pip install nselib --upgrade
Get the latest fixes — the library tracks NSE's changing endpoints closely. Installed here: 2.5.1.
from nselib import capital_market★
Import the segment module you need — there's no client object to construct and no API key anywhere.
from nselib import derivatives, indices, debt
Other segment modules. Also cash_market and nsdl_fpi (FPI/AMFI).
import nselib
Top level exposes the utilities: nselib.trading_holiday_calendar() and nselib.enable_logging().
dates = 'dd-mm-YYYY' strings★ RULE
e.g. '01-06-2024' — day-month-year, not ISO. Pass either from_date+to_date or period, never both.

02The shape of nselibhow it thinks

module.function(…) → DataFrame★ MODEL
Module = market segment, function = one NSE report, return = a pandas DataFrame (a few give a list/dict).
period='1D' '1W' '1M' '3M' '6M' '1Y'★
A rolling window ending today. Equities allow all six; futures allow 1D–6M (no 1Y).
from_date='…', to_date='…'
The alternative to period: an explicit custom range. Use one or the other.
trade_date='20-06-2024'
Reports keyed to one trading session (bhav copies, VaR, volatility, PE). Weekends/holidays → empty.
market_watch_all_indices()
Live/snapshot reports take no dates — they reflect the current session.
nselib.enable_logging(logging.DEBUG)
Silent by default; flip this on to watch the underlying HTTP requests and responses.

03Price · volume · deliverycapital_market · the workhorse

cm.price_volume_and_deliverable_position_data("SBIN", from_date="01-01-2024", to_date="31-01-2024")★ MOST USED
OHLCV plus delivery qty & % — the single richest per-stock history call.
cm.price_volume_data(symbol="INFY", period="1M")★
Just OHLCV price & volume history — lighter when you don't need delivery figures.
cm.deliverable_position_data("TCS", period="1W")
Delivery position only: TradedQty, DeliverableQty, %DlyQt-to-Traded.
symbol = NSE ticker, no suffix
"SBIN", "RELIANCE" — plain NSE symbol, no .NS. List valid ones with equity_list().

04Historical index & VIXcapital_market

cm.index_data(index="NIFTY 50", from_date="01-01-2024", to_date="31-03-2024")★
Historical index OHLC. Use the display name — "NIFTY 50", "NIFTY BANK" — not a symbol or ^NSEI.
cm.india_vix_data(period="1M")★
India VIX (volatility index) history — same date/period rules as everything else.
cm.market_watch_all_indices()
Live one-row-per-index snapshot (last, %chg, advances/declines) — no dates.
big ranges can failchunk it
Ranges over ~3–4 years may error mid-fetch. Pull in slices and pd.concat the frames.

05Bhav copies (EOD dumps)one trade_date each

cm.bhav_copy_with_delivery(trade_date="20-06-2024")★
Full end-of-day equities bhav copy + delivery for a single session — every symbol at once.
cm.bhav_copy_equities("20-06-2024")
The CM-UDiFF equities bhav copy (NSE's newer unified format).
cm.bhav_copy_sme("…") · cm.sme_band_complete("…")
SME segment bhav copy and price-band data.
fno.fno_bhav_copy(trade_date="20-06-2024")
The F&O daily bhav copy — lives in the derivatives module (see card 11).

06Symbol & universe listswho's tradable

cm.equity_list()★
Every listed equity — symbol, name, series, ISIN, listing date. Your master symbol lookup.
cm.fno_equity_list() · cm.fno_index_list()
F&O-eligible stocks and indices, with lot sizes.
cm.nifty50_equity_list()★
Nifty 50 constituents. Companions: niftynext50_, niftymidcap150_, niftysmallcap250_equity_list().
cm.total_traded_stocks()
Summary of all stocks traded — a quick breadth check.

07Deals & short sellingcapital_market · range or period

cm.bulk_deal_data(from_date="01-06-2024", to_date="30-06-2024")
Bulk deals: Date, Symbol, ClientName, Buy/Sell, Qty, weighted-avg price.
cm.block_deals_data(period="1M")
Block deals — same columns, block-window trades.
cm.short_selling_data(period="1W")
Daily short-selling report: Date, Symbol, SecurityName, Quantity.
range or period
All three accept from_date+to_date or a period — the standard time-window pair.

08Live market activitycurrent session

cm.top_gainers_or_losers(to_get="gainers")★
Top gainers in the live market.
cm.top_gainers_or_losers(to_get="loosers")double-o
Losers — spelled "loosers" in the library. Any other value raises. A genuine typo-trap. ★
cm.most_active_equities(fetch_by="value")
Most active stocks by "value" or "volume".
cm.fii_dii_trading_activity()
Daily FII vs DII buy/sell figures — the headline flows number.
empty outside market hours
Live calls reflect the current session and go empty/stale outside 09:15–15:30 IST.

09Corporate filingscapital_market

cm.corporate_actions_for_equity(period="3M", fno_only=False)
Dividends, splits, bonuses, record dates. Set fno_only=True to limit to F&O names.
cm.financial_results_for_equity(period="6M", fo_sec=True, fin_period="Quarterly")★
Filed results. fin_period = "Quarterly" / "Annual"; fo_sec=True for F&O securities only.
cm.event_calendar_for_equity(period="1M")
Upcoming board meetings & corporate events.
cm.pe_ratio(trade_date="20-06-2024")
Index-level PE/PB snapshot for a given day.
cm.corporate_bond_trade_report("…")
Corporate bond trades for a session.

10VaR, volatility & 52-wkrisk reports · one trade_date

cm.daily_volatility(trade_date="17-04-2026")
CM daily volatility report. (There's a twin derivatives.daily_volatility for F&O.)
cm.var_begin_day("…") · cm.var_end_of_day("…")
Value-at-Risk margin snapshots at start and close of the session.
cm.var_1st_intra_day("…") … var_4th_intra_day("…")
Four intraday VaR update snapshots through the trading day.
cm.week_52_high_low_report("…")
Stocks hitting 52-week highs / lows on that date.
cm.category_turnover_cash("…")
Category-wise cash-market turnover for the day.

11Derivatives: futures & optionsderivatives

fno.future_price_volume_data("SBIN", "FUTSTK", period="1M")★
Contract-wise futures history. instrument = "FUTIDX" (index) or "FUTSTK" (stock).
fno.option_price_volume_data("NIFTY", "OPTIDX", option_type="CE", period="1M")★
Options history. instrument = "OPTIDX"/"OPTSTK"; option_type = "CE"/"PE".
>90 days of options = slow
Option history is fetched contract-by-contract; large windows take noticeably longer.
fno.fno_bhav_copy(trade_date="20-06-2024")
Full F&O end-of-day bhav copy — every contract for one session.

12Live option chain & expiriesderivatives · live

fno.nse_live_option_chain("BANKNIFTY", expiry_date="27-03-2025")★
Live option chain for a symbol. Omit expiry_date to get the nearest expiry.
fno.nse_live_option_chain("NIFTY", oi_mode="compact")
oi_mode = "full" (default, all greeks/OI cols) or "compact" (fewer columns).
fno.expiry_dates_future()
List of upcoming futures expiry dates.
fno.expiry_dates_option_index()
Dict of index → upcoming option expiry dates.

13F&O flows & participantsderivatives · one trade_date

fno.fii_derivatives_statistics(trade_date="20-12-2025")★
FII index/stock futures & options — long/short contracts & value.
fno.participant_wise_open_interest("…")
OI split by Client / DII / FII / Pro participant category.
fno.participant_wise_trading_volume("…")
Traded volume by the same participant categories.
fno.fno_security_in_ban_period("…")
List of stocks in the F&O ban for that day (crossed 95% market-wide limit).
fno.live_most_active_underlying() · category_turnover_fo("…")
Live most-active underlyings; category-wise F&O turnover for a date.

14Indices moduleindices

indices.constituent_stock_list("BroadMarketIndices", "Nifty 50")★
The stocks inside a given index, with weightings. Arguments are index_category, index_name.
indices.index_list(index_category="SectoralIndices")
The index names available within one category.
indices.live_index_performances()
Live performance of every index in one frame.
categories
"BroadMarketIndices" · "SectoralIndices" · "ThematicIndices" · "StrategyIndices".

15FPI / FII activitynsdl_fpi

from nselib import nsdl_fpi
NSDL foreign-portfolio-investor flows. This module imports cleanly in 2.5.1 (unlike cash_market — see card 19).
nsdl_fpi.fetch_nsdl_fpi_investment_activity(trade_date="30-10-2025")★
FPI cash-segment investment activity for a reporting date.
nsdl_fpi.fetch_nsdl_fpi_latest_investment_activity()
Latest available FPI investment figures — no date needed.
nsdl_fpi.fetch_nsdl_fpi_derivative_activity("…")
FPI derivative activity; twin fetch_nsdl_fpi_latest_derivative_activity() for the newest.
nsdl_fpi.fetch_nsdl_fpi_month_bundle("…")
A whole month's report bundle in one object.

16Debt & AMFI fundsdebt · cash_market

debt.securities_available_for_trading(trade_date="20-12-2025")
Debt securities available for trading on a session — the whole debt module in one call.
cash_market.amfi_monthly_data(report_month="01-03-2026")
Parse one AMFI monthly mutual-fund archive report into a DataFrame.
cash_market.amfi_monthly_report_links()
List the available AMFI monthly archive links; amfi_monthly_historical_data(from_month, to_month) spans a range.
cash_market import caveat2.5.1
In 2.5.1 the cash_market module may raise ImportError on import — see card 19 for the fix.

17Business growth & turnoversegment aggregates

cm.business_growth_cm_segment(data_type="yearly", from_year="2020", to_year="2024")
Capital-market segment growth (turnover, trades, market cap) over years.
fno.business_growth_fo_segment(data_type="monthly", year="2024", month="06")
F&O segment growth. data_type = "yearly" or "monthly".
cm.category_turnover_cash("…") · fno.category_turnover_fo("…")
Turnover split by trader category (retail / prop / FII / DII …) for a day.

18Utilities · constants · loggingnselib top level

nselib.trading_holiday_calendar()★
NSE trading holidays across all segments — check before you request a trade_date.
nselib.enable_logging(logging.DEBUG)
Turn on request/response tracing; silent by default so it won't pollute your logs.
from nselib import constants
constants.dd_mm_yyyy = '%d-%m-%Y'; constants.equity_periods; constants.indices_list.
constants.*_columns
Expected column lists for many reports (e.g. price_volume_data_columns) — handy for validation.

19Gotchas & production notesread before you ship

dates are dd-mm-YYYY strings★
Passing ISO "2024-06-01" fails. It's day-month-year, e.g. "01-06-2024".
dates XOR period★
Give either from_date+to_date or period — supplying both (or an unknown period) raises ValueError.
losers = "loosers"★
top_gainers_or_losers(to_get="loosers") — the library's double-o spelling. Anything else is rejected.
NSE blocks & rate-limits★
NSE gates many non-Indian IPs and throttles bursts. Run from an Indian IP, add sleeps/retries, avoid tight loops.
cash_market / mutual_funds ImportError2.5.1
In 2.5.1 these can fail with ImportError: NSEdataNotFound. Use nsdl_fpi directly, and pip install -U nselib once patched.
index name, not symbol
index_data wants the display name "NIFTY 50" — not "NIFTY", "^NSEI", or a ticker.
live = market hours only
Option chain, gainers/losers and market_watch are empty or stale outside 09:15–15:30 IST.
unofficial & read-only
No affiliation with NSE; scrapes public pages. For personal research — not production trading.

nselib cheat sheet

Four ideas worth a picture

1 · Anatomy of a call

2 · Two ways to bound time

3 · The segment map

4 · Derivatives decoder

Worth memorizing