/finlab

name: finlab
description: Comprehensive guide for FinLab quantitative trading package across global stock markets (TW, US, KR, JP, HK; both single-name equities and ETFs/funds). Use when working with trading strategies, backtesting, stock data, FinLabDataFrame, factor analysis, stock selection, or when the user mentions FinLab, trading, quant trading, US equity, S&P 500 / NASDAQ 100, SPY / QQQ, sector or leveraged ETFs, ETF rotation, 美股, or stock market analysis. Includes data access, strategy development, backtesting workflows, best practices, and US-market specifics (data availability map, filing-date-aligned quarterly fundamentals, US universe construction, USMarket vs. USFundMarket defaults, and ETF backtesting).
compatibility: Requires Python 3.10+ and uv package manager (https://docs.astral.sh/uv/)

FinLab Quantitative Trading Package

Prerequisites

**Before running any FinLab code, verify these in order:**

1. **uv is installed** (Python package manager):

   uv --version

If uv is not installed, tell the user to install it.

After installing, ensure `uv` is on PATH:

   source $HOME/.local/bin/env 2>/dev/null  # Add uv to current shell

2. **FinLab is installed via uv** (requires >= 2.0.0):

   uv python install 3.12  # Ensure Python is available (skip if already installed)
   uv pip install --system "finlab>=2.0.0" 2>/dev/null || uv pip install "finlab>=2.0.0"

**Or use `uv run` for zero-setup execution** (recommended for one-off scripts):

   uv run --with "finlab" python3 script.py

`uv run --with` auto-creates a temporary environment with dependencies — no venv management needed.

**Prefer zero-install?** Run notebooks directly in [FinLab Studio](https://studio.finlab.finance) — a hosted Jupyter environment with `finlab` preinstalled and your account already logged in.

3. **Logged in to FinLab** (required - data access fails without it):

**Desktop (has a browser):** log in once, then just import:

   python -m finlab login   # opens the FinLab (Firebase) browser login; credentials are cached locally

   import finlab            # cached credentials are picked up automatically
   finlab.login()           # optional: reuses cached credentials, or starts the browser login if none

`finlab.login()` opens a FinLab browser login (Firebase auth). Without a TTY it prints a login URL that can be opened on any device.

**Headless / cron / Docker:** on a machine with a browser, log in and run `python -m finlab token --env`, then set the printed `FINLAB_REFRESH_TOKEN`, `FINLAB_SESSION_ID` and `FINLAB_API_KEY` environment variables on the headless machine.

**Google Colab:** run `finlab.login()` in a cell.

Do not use `FINLAB_API_TOKEN` or `finlab.login('<api_token>')` — the legacy API-token login is deprecated (`python -m finlab migrate` shows the migration guide).

Language

**Respond in the user's language.** If user writes in Chinese, respond in Chinese. If in English, respond in English.

Market Support

FinLab supports TW (default), US, KR, JP, HK, plus Taiwan emerging (`rotc`) and Taiwan convertible bonds (`tw_cb`). Pick the market once per session with `data.set_market(<code>)`; generic dataset names like `price:收盤價` or `monthly_revenue:當月營收` resolve to the active market's tables, so strategy code is written the same way across markets. `data.set_market('rotc')` *(v2.0.9)* enables 興櫃 (TW emerging) — use it when you need pre-listing price action or revenue factors that don't exist in the main TSE/OTC catalog.

The rest of this file plus [dataframe-reference.md](dataframe-reference.md), [backtesting-reference.md](backtesting-reference.md), [best-practices.md](best-practices.md), [factor-analysis-reference.md](factor-analysis-reference.md), and [machine-learning-reference.md](machine-learning-reference.md) are **market-agnostic** — the APIs behave the same across markets.

For US-market work — whether single-name equities (`data.set_market('us')`) or ETFs/funds (`data.set_market('us_fund')`) — **read [us-market.md](us-market.md) first**. Queries that should trigger it include: US equity, S&P 500, NASDAQ 100, 美股, SPY / QQQ, sector SPDRs, leveraged / inverse ETFs, ETF rotation, `us_price:*`, `us_fund_price:*`, `data.us_universe(...)`, or `us_income_statement:*` / `us_cash_flow:*` / `us_balance_sheet:*`. It documents:

• Which US data tables are safe for backtesting versus current-snapshot-only (analyst consensus, ratios, DCF are live-only — do not use them historically)
• Filing-date-aligned quarterly fundamentals (`key_date == filing_date`) — no `.shift()` workaround needed
• `Report` API names on US (`creturn` / `daily_creturn` / `get_stats()`; no `get_equity()`)
• US backtest defaults for both markets: `USMarket` (`fee_ratio=0`, `tax_ratio=0`, `trade_at_price='close'`) and `USFundMarket` for ETF/fund backtests
• How `data.set_market(...)` is the session-scope switch (there is no `market=` kwarg on `data.get()`)
• Dollar-volume-top-N universe construction (works back to 2016), S&P 500 / NASDAQ 100 membership via `data.us_universe(index='S&P 500' | 'NASDAQ 100')` with its 2022-11 history-start caveat, quality gates, and sector-exclusion rationale
• Lookahead-bias checklist specific to US data (rolling-window universe filters, survivorship avoidance)
• ETF / sector-rotation backtesting via `USFundMarket` and `us_fund_price:*`

Other-market queries can skip that file.

Account Tiers & Usage

Tiers

| Tier | Daily Limit | | ---- | ----------- | | Free | 500 MB | | VIP | 5000 MB |

Check the current plan and quota with `python -m finlab status`.

Usage Reset

• Resets daily at **8:00 AM UTC+8**
• When limit exceeded, user must wait for reset or upgrade to VIP at [finlab.finance](https://finlab.finance)

Quick Start Example

from finlab import data
from finlab.backtest import sim

# 1. Fetch dat