finlab

The finlab module handles login and credentials. Log in once in a browser on your own computer or in Colab and it is reused from then on; environments without a browser, such as servers, Docker and schedulers, use environment-variable credentials instead.

Which function to use

Log in on your computer or in Colab

Your own computer (recommended)

Run this once in a terminal; every Python session on the same machine then reuses the stored credentials:

python -m finlab login

Or log in from Python / Jupyter:

import finlab

# 1. Call login() without arguments
# 2. The browser opens the FinLab login page automatically
finlab.login()

# 3. After a successful login, credentials are saved to ~/.finlab/credentials.json
# 4. No need to log in again for subsequent use

• Credential storage location: ~/.finlab/credentials.json
• Validity period: 60 days (auto-refreshes)

If browser login fails, is rejected, or times out, finlab.login() raises finlab.exceptions.LoginError (a RuntimeError subclass) instead of returning silently.

Google Colab

import finlab

finlab.login()  # follow the prompt to finish logging in in the browser

finlab.login()

Logs in to FinLab; called without arguments, it starts the browser login.

import finlab

finlab.login()

On success the credentials are saved to ~/.finlab/credentials.json and reused automatically on the same machine. In Colab, call finlab.login() the same way. For environments without a browser (servers, schedulers), run python -m finlab token --env on your own machine and set FINLAB_REFRESH_TOKEN, FINLAB_SESSION_ID and FINLAB_API_KEY.

Returns None. Raises LoginError when the browser login fails, is rejected, or times out.

Use it on servers, Docker and schedulers

Environments without a browser don't call finlab.login(). First export credentials on a machine where you are logged in:

python -m finlab token --env
# export FINLAB_REFRESH_TOKEN="..."
# export FINLAB_SESSION_ID="..."
# export FINLAB_API_KEY="..."

Then set these three values as environment variables in the target environment (docker-compose, GitHub Actions secrets, Cloud Functions variables, ...). Your code does not need to call finlab.login():

from finlab import data

data.set_market('us')
close = data.get('price:adj_close')  # picks up FINLAB_REFRESH_TOKEN etc. automatically

Check your login and log out

Check the status or log out in a terminal:

python -m finlab status   # show login status and plan
python -m finlab logout   # clear local credentials and remove the server session

If you set environment-variable credentials, also remove FINLAB_REFRESH_TOKEN, FINLAB_SESSION_ID, FINLAB_API_KEY (and the legacy FINLAB_API_TOKEN) when you log out.

finlab.get_token()

Returns the authentication token of the logged-in member; use it to check in code whether you are logged in.

import finlab

try:
    token, token_type = finlab.get_token()
    print(f"✅ Logged in ({token_type})")
except RuntimeError:
    print("❌ Not logged in")

Credentials are looked up in this order:

1. Login credentials: the FINLAB_REFRESH_TOKEN, FINLAB_SESSION_ID and FINLAB_API_KEY environment variables when all three are set, otherwise ~/.finlab/credentials.json from browser login; returns an id_token
2. The FINLAB_ID_TOKEN environment variable, returns an id_token
3. The legacy FINLAB_API_TOKEN environment variable, returns an api_token
4. Interactive login

Takes no parameters. Returns a tuple of (token_string, token_type), where token_type is 'id_token' or 'api_token'.

How FinLab finds your credentials

FinLab looks for credentials in the following order:

1. FINLAB_REFRESH_TOKEN + FINLAB_SESSION_ID + FINLAB_API_KEY environment variables (only when all three are set)
2. ~/.finlab/credentials.json: credentials generated by browser login
3. FINLAB_ID_TOKEN environment variable: used by browser / Pyodide runtimes
4. FINLAB_API_TOKEN environment variable: legacy API token (deprecated, warns)
5. Interactive login: starts browser login if none of the above exist

Common questions

Next steps