PyPortfolioOpt Documentation

PyPortfolioOpt is a modular library for portfolio optimization. Its core functionality is divided into four related areas:

1. Expected returns: Estimating the future returns of assets.
2. Risk models (covariance): Estimating the covariance of asset returns.
3. Objective functions: Defining what to optimize (e.g., Sharpe ratio, volatility).
4. Optimizers: The engines that solve the optimization problems (e.g., EfficientFrontier).

This example demonstrates the full workflow: reading price data, calculating expected returns and sample covariance, and using the EfficientFrontier class to find the optimal weights for a maximal Sharpe ratio portfolio.

import pandas as pd
from pypfopt import EfficientFrontier
from pypfopt import risk_models
from pypfopt import expected_returns

# Read in price data
df = pd.read_csv("tests/resources/stock_prices.csv", parse_dates=True, index_col="date")

# Calculate expected returns and sample covariance
mu = expected_returns.mean_historical_return(df)
S = risk_models.sample_cov(df)

# Optimize for maximal Sharpe ratio
ef = EfficientFrontier(mu, S)
raw_weights = ef.max_sharpe()
cleaned_weights = ef.clean_weights()
ef.save_weights_to_file("weights.csv")  # saves to file

for name, value in cleaned_weights.items():
    print(f"{name}: {value:.4f}")

You can install the library directly from PyPI using pip.

pip install pyportfolioopt

For best practices, use a dependency manager like poetry. Within a new poetry project, run the following command to add PyPortfolioOpt as a dependency.

poetry add PyPortfolioOpt

Use the DiscreteAllocation class to convert optimized weight vectors into specific quantities of shares to purchase, given a total portfolio value and the latest asset prices.

from pypfopt.discrete_allocation import DiscreteAllocation, get_latest_prices

latest_prices = get_latest_prices(df)
da = DiscreteAllocation(w, latest_prices, total_portfolio_value=20000)
allocation, leftover = da.lp_portfolio()
print(allocation)

Mean-variance optimization often results in many negligible weights. To coerce the optimizer to produce more non-negligible weights (a more distributed portfolio), use L2 Regularization. This adds a penalty term proportional to the sum of squared weights to the objective function.

In the objective_functions module, use L2_reg to apply this penalty. The strength of the regularization is controlled by the gamma parameter.

Tuning gamma:

• For small asset universes (< 20 assets): gamma=1 is a good starting point.
• For larger universes or when more diversification is needed: Increase gamma.

The EfficientFrontier class is used to find optimal asset allocations. To find the portfolio that maximizes the Sharpe ratio, use the max_sharpe() method.

After optimization, use clean_weights() to truncate tiny weights to zero and round the remaining weights for a cleaner output. You can also use portfolio_performance(verbose=True) to see the expected annual return, volatility, and Sharpe ratio.

from pypfopt.efficient_frontier import EfficientFrontier

ef = EfficientFrontier(mu, S)
weights = ef.max_sharpe()

cleaned_weights = ef.clean_weights()
ef.save_weights_to_file("weights.txt")  # saves to file
print(cleaned_weights)

ef.portfolio_performance(verbose=True)

PyPortfolioOpt supports Docker (requires make, docker, and docker-compose).

• Build the container: make build
• Run tests: make test