Okama
okama is a Python library for investment portfolio analysis and optimization. It applies concepts commonly used in quantitative finance.
okama provides access to free end-of-day historical market data and macroeconomic indicators through an API.
...entities should not be multiplied without necessity
-- William of Ockham (c. 1287–1347)
Table of contents
- Okama main features
- Financial data and macroeconomic indicators
- Installation
- Getting started
- Examples
- Documentation
- Financial Widgets
- MCP server
- Roadmap
- Contributing to okama
- Communication
Okama main features
- Investment portfolio constrained Markowitz Mean-Variance Analysis (MVA) and optimization
- Rebalanced portfolio optimization with constraints (multi-period Efficient Frontier)
- Advanced rebalancing strategies: Rebalancing-bands (threshold-based), Calendar-based or hybrid
- Investment portfolios with complex contributions / withdrawals cash flows (DCF)
- Multi-stage financial plans with
FinPlanandFinPlanStage, carrying balances between stages per Monte Carlo path - Money-weighted internal rate of return (IRR/MWRR) for portfolio cash flows — on historical data and across Monte Carlo forecast paths
- Monte Carlo Simulations for financial assets and investment portfolios, reproducible with a random
seed - Forecasting with popular theoretical distributions: normal, lognormal and Student's (T)
- Degrees of freedom optimization for Student's t-distribution to fit well at a given confidence level
- Testing distributions on historical data
- Popular risk metrics: VAR, CVaR, semi-deviation, variance and drawdowns
- Different financial ratios: CAPE10, Sharpe ratio, Sortino ratio, Diversification ratio
- Dividend yield and other dividend indicators for stocks
- Backtesting and comparing historical performance of a broad range of assets and indexes in multiple currencies
- Methods to track the performance of index funds (ETF) and compare them with benchmarks
- Main macroeconomic indicators: inflation, central banks rates
- Matplotlib visualization scripts for the Efficient Frontier, Transition map and assets risk / return performance
Financial data and macroeconomic indicators
End of day historical data
- Stocks and ETF for main world markets
- Mutual funds
- Commodities
- Stock indexes
Currencies
- FX currencies
- Crypto currencies
- Central bank exchange rates
Macroeconomic indicators
For many countries (China, USA, United Kingdom, European Union, Russia, Israel etc.):
- Inflation
- Central bank rates
- CAPE10 (Shiller P/E) Cyclically adjusted price-to-earnings ratios
Other historical data
- Real estate prices
- Top bank rates
Installation
Requirements
- Python 3.11 or newer
- Core dependencies: pandas, numpy, scipy (plus
matplotlib,pyarrow,statsmodels,archand others). See pyproject.toml for the full list of dependencies and version constraints.
Install from PyPI
pip install okama
Or with uv:
uv add okama # add to a uv-managed project
uv pip install okama # or pip-style install into the active environment
Install the latest development version from GitHub
Install uv first. The contributor environment defaults to Python 3.14; the library supports Python 3.11–3.14.
git clone -b dev https://github.com/mbk-dev/okama.git
cd okama
uv sync
uv run python -c "import okama; print(okama.__version__)"
uv sync includes the test, docs, Jupyter and dev groups. For local notebooks,
see the examples setup.
Getting started
1. Compare several assets from different stock markets. Get USD-adjusted performance
import okama as ok
x = ok.AssetList(["SPY.US", "BND.US", "DBXD.XFRA"], ccy="USD")
x
Get the main parameters for the set:
x.describe()
Get the assets accumulated return, plot it and compare with the USD inflation:
x.wealth_indexes.plot()
2. Create a dividend stocks portfolio with base currency EUR
weights = [0.3, 0.2, 0.2, 0.2, 0.1]
assets = ["T.US", "XOM.US", "FRE.XFRA", "SNW.XFRA", "LKOH.MOEX"]
pf = ok.Portfolio(assets, weights=weights, ccy="EUR")
pf.table
Plot the dividend yield of the portfolio (adjusted to the base currency).
pf.dividend_yield.plot()
3. Draw an Efficient Frontier for 2 popular ETF: SPY and GLD
ls = ["SPY.US", "GLD.US"]
curr = "USD"
last_date = "2020-10"
# Rebalancing period is one year (default value)
frontier = ok.EfficientFrontier(ls, last_date=last_date, ccy=curr, rebalancing_strategy=ok.Rebalance(period="year"))
frontier.names
Get the Efficient Frontier points for rebalanced portfolios and plot the chart with the assets risk/CAGR points:
import matplotlib.pyplot as plt
points = frontier.ef_points
fig = plt.figure(figsize=(12, 6))
fig.subplots_adjust(bottom=0.2, top=1.5)
frontier.plot_assets(kind="cagr") # plots the assets points on the chart
ax = plt.gca()
ax.plot(points.Risk, points.CAGR)
4. Get a Transition Map for allocations
ls = ["SPY.US", "GLD.US", "BND.US"]
ok.EfficientFrontier(ls, ccy="USD").plot_transition_map(x_axe="risk")
Examples
More examples are available as Jupyter Notebooks:
- howto — main features of the okama package:
Asset,AssetList, andPortfolioobjects. - index funds performance — compare ETFs and mutual funds with their benchmarks: tracking difference, tracking error, beta, and correlation.
- investment portfolios — portfolio properties and comparison of multiple portfolios.
- investment portfolios with DCF — portfolio strategies with cash flows (withdrawals and contributions), backtesting and longevity forecasts with Monte Carlo simulation.
- macroeconomics — historical inflation, key rates, and other macroeconomic indicators.
- efficient frontier single period — classic Markowitz frontiers with monthly rebalanced portfolios (
EfficientFrontierSingle). - efficient frontier multi-period — multi-period optimization with custom rebalancing frequencies or without rebalancing.
- backtesting distribution — backtest portfolio return distributions with Jarque-Bera, Kolmogorov-Smirnov, and related diagnostics.
- financial database — query the okama database for stocks, ETFs, mutual funds, indexes, currencies, and macroeconomic data.
- forecasting — forecast portfolio performance with normal, lognormal, Student's t, and historical distributions.
- rebalancing portfolio — compare calendar-based, threshold-based, and hybrid portfolio rebalancing strategies.
Documentation
The official documentation is hosted on readthedocs.org: https://okama.readthedocs.io/
Financial Widgets
okama.io offers interactive financial widgets (multi-page web application) powered by the okama package. The current platform combines React and Django, with remaining legacy widgets maintained in Dash. Working example is available at okama.io.
MCP server
okama-mcp is an MCP (Model Context Protocol) server that exposes the okama toolkit to AI assistants — Claude Desktop, Claude Code, Cursor, and any other MCP-compatible client. Ask the AI to backtest a portfolio, build an efficient frontier, or run a Monte Carlo retirement forecast — it calls okama directly, no Python code needed.
uvx okama-mcp stdio # run straight from PyPI
okama-mcp is free and open source — no hosted service, no registration; you run it yourself, locally or on your own server. See mcp.okama.io for installation and client configuration.
Roadmap
The plan for okama is to add more functions that will be useful to investors and asset managers.
- Add multidimensional Monte Carlo with Ledoit-Wolf shrinkage
- Add Omega ratio to EfficientFrontier and Portfolio classes.
- Add Black-Litterman asset allocation
- Add different utility functions for optimizers: IRR, portfolio survival period, semi-deviation, VaR, CVaR, drawdowns etc.
- Add more functions based on suggestions from users.
Contributing to okama
Contributions are most welcome. Have a look at the Contribution Guide for more.
Feel free to ask questions on Discussions.
As contributors and maintainers to this project, you are expected to abide by okama's code of conduct. More information can be found at: Contributor Code of Conduct
Communication
For basic usage questions (e.g., "Is XXX currency supported by okama?") and for sharing ideas please use GitHub Discussions. Russian language community is available at okama.io forums.
Explore the okama family
Tools for investing and financial planning.
| Project | What it helps you do |
|---|---|
| okama.io | Explore portfolios with interactive web tools. |
| okama Data API | Access historical market and economic data. |
| okama-macro | Work with inflation and central-bank rate series. |
| okama-mcp | Use okama tools through an AI assistant. |
| okama Planner | Build financial plans and manage client planning history. |
Ask questions, share examples and discuss financial planning.
Metadata
Release files for okama 4.0.1
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| okama-4.0.1.tar.gz | 149.1 kB | Without provenance | Details for okama-4.0.1.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| okama-4.0.1-py3-none-any.whl | Python 3 | none | any | Details for okama-4.0.1-py3-none-any.whl |
Total release size: 312.4 kB
Release files / okama-4.0.1.tar.gz
| Download URL | okama-4.0.1.tar.gz |
|---|---|
| Size | 149.1 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
2d13b5de18b0b9531e2c149dc1d98701f075bb19465911a676c68929b981b0d9
|
|
BLAKE2b-256 checksum How to use checksums |
aceda841c86bd86cab4948a2708d102f19f57b0c2e1a8f78a87e8077b188877a
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.12.23 {"installer":{"name":"uv","version":"0.12.23","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"26.04","id":"resolute","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}
|
Release files / okama-4.0.1-py3-none-any.whl
| Download URL | okama-4.0.1-py3-none-any.whl |
|---|---|
| Size | 163.2 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
43a4ac4be866ea3a2f9708c64a5a7fb944aad283a87b0574a9b3709310fb1ba2
|
|
BLAKE2b-256 checksum How to use checksums |
267d3ad9645b4b97d66f5452affd7b744688f336b42e3e449abc48389b606139
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.12.23 {"installer":{"name":"uv","version":"0.12.23","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"26.04","id":"resolute","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}
|
Security for okama 4.0.1
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.