pyjpx-etf

A clean, beginner-friendly Python library for fetching JPX ETF portfolio composition (PCF) data, ranking ETFs by returns, and analyzing holdings.

Installation

pip install pyjpx-etf

Quick Start

import pyjpx_etf as etf

# ETF lookup (auto-syncs local DB on first use)
e = etf.ETF("1306")
print(e.info.name)       # "TOPIX連動型上場投資信託"
print(e.nav)             # total fund NAV in yen
print(e.fee)             # trust fee (%) e.g. 0.06
print(e.holdings[:3])
# [Holding(code='7203', name='トヨタ自動車', ...),
#  Holding(code='8306', name='三菱UFJフィナンシャル・グループ', ...),
#  Holding(code='6758', name='ソニーグループ', ...)]

Python API

ETF Ranking

etf.ranking()              # top 10 by 1-month return
etf.ranking("1y", n=20)    # top 20 by 1-year return
etf.ranking("ytd", n=-5)   # worst 5 by ytd return

Reverse Stock Search

etf.search("6857")         # which ETFs hold Advantest?
etf.search("7203", n=5)    # top 5 ETFs holding Toyota

Weight History

etf.history("1306", "6857")  # Advantest weight in TOPIX over time
etf.history("1306")          # top holdings with weight change

Language & Config

etf.config.lang = "en"          # "ja" (default) or "en"
etf.config.timeout = 60         # HTTP timeout in seconds
etf.config.request_delay = 0.5  # delay between retries

CLI

ETF Lookup

$ etf 1306

1306 — TOPIX連動型上場投資信託 (2026-02-27)
Nav: 5170億  信託報酬: 0.06%

 Code   Name                                Weight
─────  ──────────────────────────────────  ──────
 7203   トヨタ自動車                          3.7%
 8306   三菱ＵＦＪフィナンシャル・グループ    3.3%
 6501   日立製作所                            2.4%
 ...

$ etf topix --en -a     # English, all holdings
$ etf 1306 --live       # skip local DB, fetch live

ETF Ranking

$ etf rank                # top 10 by 1-month return
$ etf rank 20 1y          # top 20 by 1-year return
$ etf rank -5 ytd --en    # worst 5 by ytd, English names

Available periods: 1m (default), 3m, 6m, 1y, 3y, 5y, 10y, ytd

Stock Search

$ etf find 6857            # ETFs holding Advantest
$ etf find 7203 5          # top 5 ETFs holding Toyota
$ etf find 6857 --en       # English names

Weight History

$ etf history 1306 6857    # Advantest weight in TOPIX over time
$ etf history 1306         # top holdings with weight change
$ etf history 1306 --en    # English names

Database Sync

The local database auto-syncs on first use each day. To force a refresh:

$ etf sync                 # download/update
$ etf sync --force         # force re-download

ETF Screener

Screen all ETFs by trading activity, volatility, fund size, or fees. Requires the optional screen extra:

pip install 'pyjpx-etf[screen]'

$ etf screen                    # top 20 by range_pct
$ etf screen --by vol_ratio     # volume surges
$ etf screen --by aum --top 10  # top 10 by fund size

Aliases

Options

$ etf --help               # show all commands
$ etf --version            # show version

Documentation

Full documentation