skfolio: Portfolio Optimization in Python with the scikit-learn API

What Problem skfolio Solves for Portfolio Researchers

Mean-variance optimisation, developed by Markowitz in 1952, remains a standard framework for portfolio allocation but carries well-documented shortcomings: high sensitivity to estimated expected returns and covariance matrices, concentration in a few assets, high turnover, and poor out-of-sample performance. Research has shown that naive equal-weight allocation (1/N) often outperforms MVO out of sample.

The response from the research community has been a proliferation of methods to address these failures: shrinkage estimators, uncertainty sets, higher moments, Bayesian priors, coherent risk measures, hierarchical clustering, and ensemble approaches. Managing these methods in a consistent experimental environment is difficult when each requires a different implementation, a different data interface, and different cross-validation logic.

skfolio exists to provide a unified framework for this problem. It follows the scikit-learn API, which means any skfolio estimator plugs directly into sklearn's cross-validation tools, pipeline constructors, and parameter search infrastructure. The target users are quantitative analysts, financial data scientists, and researchers who want to select, validate, and tune portfolio models with the same discipline applied to machine learning models.

Architecture: scikit-learn Compatibility as the Core Design Decision

The decision to follow scikit-learn's API is not cosmetic. It means skfolio's Portfolio Optimization estimators implement the same fit and transform interface that all sklearn estimators use. A portfolio model can be placed inside a Pipeline alongside preprocessing steps, evaluated with cross_val_score, and tuned with GridSearchCV, all without any skfolio-specific tooling.

The library includes tools for mitigating data leakage during cross-validation, which is a specific hazard in financial modelling: asset returns have autocorrelation and calendar effects that make naive train-test splits misleading. skfolio's walk-forward cross-validation and combinatorial purged cross-validation tools address this.

The library is structured into several functional areas: Portfolio Optimization estimators (including naive, convex, clustering, and ensemble variants), Prior Estimators (for modelling expected returns and covariances), and data preparation utilities. The pyproject.toml shows it targets Python 3.10 through 3.14. The repository includes an examples/ directory with subdirectories covering mean_risk, clustering, factor_models, model_selection, entropy_pooling, risk_budgeting, and synthetic_data scenarios.

Installing skfolio and Running a First Optimisation

Installation requires Python 3.10 or later. The README gives the standard pip install command:

pip install -U skfolio

The -U flag installs the latest available version. The README notes that the full installation guide at skfolio.org covers additional options including conda-forge and mixed-integer solver dependencies, which are required for some optimisation methods.

skfolio provides LLM-friendly documentation under the llms.txt convention: the file at skfolio.org/llms.txt provides an index, individual documentation pages are available as Markdown by appending .md to their HTML URLs, and skfolio.org/llms-full.txt contains the complete documentation in a single file. The library is currently at version 1.4.5, released on 2026-09-28.

Available Models: From Naive Allocation to Ensemble Methods

skfolio's portfolio optimisation catalogue covers four categories. Naive methods include Equal-Weighted, Inverse-Volatility, and Random (Dirichlet) allocation, which serve as baselines. Convex methods include Mean-Risk, Risk Budgeting, Maximum Diversification, Distributionally Robust CVaR, and a Benchmark Tracker.

Clustering methods implement hierarchical approaches: Hierarchical Risk Parity (HRP), Hierarchical Equal Risk Contribution, Schur Complementary Allocation, and Nested Clusters Optimization. The ensemble category provides a Stacking Optimisation method that combines predictions from multiple component models.

The Prior Estimators section is equally broad. It covers an Empirical estimator alongside a Characteristics-Based Cross-Sectional Factor Model with 46 descriptors across 17 families (value, size, momentum, profitability, and others). Additional estimators include Time-Series Factor Models, Black-Litterman, Synthetic Data generation for stress testing, Entropy Pooling, and Opinion Pooling. Each of these is a distinct, documented class in the library's API.

Limitations and Cases Where skfolio May Not Be the Right Tool

skfolio does not include execution or order management components. It is a modelling and optimisation library, not a trading system. Users who need to connect portfolio weights to broker APIs or execution venues must handle that layer separately.

The optimisation methods that use mixed-integer programming require additional solver dependencies beyond the base install. The README directs users to the installation guide for details on which solvers are compatible and how to install them. Users who skip this step and attempt to use those methods will encounter missing dependency errors.

The library targets Python 3.10 and later. Projects running older Python versions cannot use it without a version upgrade. The dependency tree is substantial: the pyproject.toml lists numpy, scipy, pandas, scikit-learn, and several statistical and optimisation libraries as direct dependencies, which means the install footprint is large compared to a purpose-built single-method implementation.

skfolio vs. Riskfolio-Lib

Riskfolio-Lib is an alternative Python portfolio optimisation library that covers a similar range of methods. Both libraries provide HRP, risk-parity variants, and various risk measures. The documented difference in approach is that skfolio is built on scikit-learn's API as the foundation: its estimators implement fit and transform, enabling direct use of sklearn's cross-validation and pipeline tools without any adapter layer. Riskfolio-Lib has its own interface and cross-validation utilities.

For users already working in sklearn pipelines, skfolio's compatibility with that toolchain is a concrete advantage. For users who prefer a standalone portfolio library with no sklearn dependency, Riskfolio-Lib represents a different trade-off. Claims about Riskfolio-Lib's current feature set should be verified from its own documentation, as both libraries evolve independently.

Maintenance, Enterprise Support, and License

skfolio is under active development. The last push to the main branch was on 2026-09-27, and three releases were tagged within the preceding two days: v1.4.5 on 2026-09-28, v1.4.4 earlier the same day, and v1.4.3 on 2026-09-27. The release cadence is rapid.

The project is backed by Skfolio Labs, which offers enterprise support and SLAs for institutional users. This is documented in the README and in the pyproject.toml maintainer fields. The library has been cited in the textbook Portfolio Optimization: Theory and Application by Daniel P. Palomar, which uses skfolio for Python code examples.

The library is distributed under the BSD-3-Clause licence. This licence permits commercial use, modification, and distribution with attribution, but restricts using the project name or contributor names in promotional materials without prior permission.

Editorial conclusion

Quantitative analysts, data scientists, and researchers who already work within the scikit-learn ecosystem and want to apply rigorous cross-validation to portfolio allocation models will find skfolio a well-structured fit. The library's depth is significant: it covers naive allocation, convex risk-budget models, hierarchical clustering methods, factor models including 46 descriptors across 17 families, Black-Litterman, Entropy Pooling, and ensemble methods in a single coherent API. Users who need models that fall outside skfolio's documented catalogue, or who work in environments where the BSD-3-Clause licence creates concerns, should verify coverage before committing. Skfolio Labs offers enterprise support and SLAs for institutional users.

Frequently asked questions

Official sources

1. License: BSD-3-Clause
2. Project website
3. README
4. Releases
5. skfolio/skfolio on GitHub