# FinRL-X (FinRL-Trading): a weight-centric Python stack for backtest-to-broker strategies

> FinRL-X is the successor to FinRL, built around one interface contract: a target portfolio weight vector. This review covers how the pipeline works, how to install it, and where the design breaks down.

**AI4Finance-Foundation/FinRL-Trading** — FinRL-X: An AI-Native Modular Infrastructure for Quantitative Trading

- Repository: https://github.com/AI4Finance-Foundation/FinRL-Trading
- Website: https://ai4finance.org
- Stars: 3,764 · Forks: 1,101
- Language: Python
- License: Apache-2.0
- Published: 2026-09-23 · Updated: 2026-09-23 · Language: en
- Canonical page: https://hysenlabs.com/projects/ai4finance-foundation-finrl-trading

## The problem FinRL-X solves is interface drift, not model quality

Most quant codebases rot at the seams. A researcher writes a stock selector, a colleague writes an allocator, someone else writes the backtest loop, and the live trader is written a fourth time by whoever is on call. The four pieces agree on a DataFrame shape until they do not, and the divergence shows up as a live P&L that does not match the backtest. FinRL-X attacks that specific failure. Its README states the target portfolio weight vector is the sole interface contract between strategy logic and downstream execution, expressed as a composition of four stages: stock selection, portfolio allocation, timing adjustment, and portfolio-level risk overlay. The intended audience is researchers and practitioners who want to swap an equal-weight allocator for a DRL allocator without rewriting the execution path. That is a narrower and more useful claim than "AI trading platform". If you only ever run one strategy with one allocator, the contract buys you nothing and the extra indirection is a cost.

## How the four-stage weight pipeline is wired

The repository layout is the clearest description of the data flow. Under src/, data/data_fetcher.py pulls from Yahoo Finance, FMP or WRDS, data/data_processor.py does feature engineering and cleaning, and data/data_store.py persists to SQLite with caching. Strategies live in src/strategies/, with base_strategy.py defining the abstract framework and ml_strategy.py implementing Random Forest stock selection. The backtest engine in src/backtest/backtest_engine.py is built on the bt library and adds multi-benchmark comparison and transaction costs. Execution sits in src/trading/: alpaca_manager.py handles multi-account Alpaca integration, trade_executor.py handles order management and risk controls, and performance_analyzer.py tracks P&L. The README describes each stage as contract-preserving, so an equal-weight allocator can be replaced by a PPO or SAC allocator while the timing overlay and risk overlay keep consuming the same input shape. The paper reference is arXiv:2603.21330. A detail worth noting: ML_STOCK_SELECTION.md exists at the repository root, which suggests the selection stage has documentation that did not fit in the README.

## Installing finrl-trading and running a first backtest

The package is published on PyPI as finrl-trading, and the README targets Python 3.11 or later. The recommended entry point is the notebook at examples/FinRL_Full_Workflow.ipynb, which the repository itself labels as the place to start. Configuration is centralized in src/config/settings.py, which the README describes as Pydantic-based settings plus environment variables. A .env.example file sits at the repository root, and docker-compose.yml mounts ./.env into the container, so provider keys are supplied through that file rather than through code. If you prefer containers, the Dockerfile builds on python:3.11-slim, installs requirements.txt, copies src/, and sets the default command to the CLI dashboard. The compose file maps port 8501 and mounts ./data, ./logs and ./.env into the container.

```yaml
ports:
  - "8501:8501"
volumes:
  - ./data:/app/data
  - ./logs:/app/logs
  - ./.env:/app/.env
```

With that running, the dashboard is served on 8501 and the healthcheck imports the config package to confirm the image is sane. Two optional services, PostgreSQL 15 and Redis 7, are defined behind the production profile, so they do not start by default. For a first real use, open examples/FinRL_Full_Workflow.ipynb and follow it end to end before touching the live trading modules; that notebook is the only complete walkthrough the repository points at.

## Where the weight contract leaks: costs, lookahead and broker scope

The weight vector is a clean abstraction, but it does not carry everything a strategy needs to be honest. Transaction costs are handled by the backtest engine rather than by the strategy contract, so a DRL allocator trained against a frictionless objective learns weights the execution layer will not reproduce once costs are applied. The repository acknowledges this by shipping examples/compare_cost_models.ipynb, which exists precisely because the choice of cost model changes the answer. Use Case 2 in the README claims strict no-lookahead semantics for quarterly selection of the top 25% of NASDAQ-100 stocks, but that guarantee is a property of that strategy's implementation, not of the weight interface itself; nothing in the contract prevents a future module from reading forward data. The execution layer is also narrower than the marketing suggests. alpaca_manager.py integrates Alpaca, and the README lists no second broker. If your mandate is futures, crypto or a European venue, the execution half of the stack does not apply to you. Finally, setup.py carries the classifier Development Status :: 4 - Beta, and its read_requirements function filters out lines beginning with tensorflow or torch, so a source install silently omits the deep learning dependency that the DRL allocators need. That is a real footgun: a source install will succeed and the PPO path will fail at import.

## FinRL-X versus the original FinRL and versus bt alone

The README positions FinRL-X as the successor to the original FinRL framework, with a modernized architecture aimed at the LLM and agentic era. The practical difference is where the abstraction sits. FinRL's lineage is organized around environments and agents in a reinforcement learning loop; FinRL-X reorganizes the same problem around a weight vector that any method, classical or learned, can produce. That makes classical baselines first-class citizens: the README's Use Case 1 table lists Equal Weight, Mean-Variance and Minimum Variance alongside a PPO/SAC DRL allocator and a KAMA timing overlay, all emitting the same output. Against bt alone, the distinction is scope. bt gives you a backtesting engine and nothing else; FinRL-X wraps bt and adds the data pipeline, the strategy contract and the Alpaca execution path, at the cost of a much larger dependency surface, including openai, streamlit, finnhub, lightgbm and xgboost. If your work stops at research and you already have a data layer, bt plus your own loader is less machinery.

## Maintenance, licensing and what an upgrade actually costs

The last push to the master branch was on 2026-09-18, and the repository is not archived. The only release listed is v1.0.0 from 2026-03-25, titled Initial Public Release. Note the version mismatch: setup.py declares version 2.0.2 while the release history shows 1.0.0, so the PyPI artifact and the Git tag are not obviously the same thing. Anyone pinning a version should check both. The licence is Apache-2.0, which permits commercial use and modification and includes a patent grant; it also requires that you preserve notices and state significant changes. That is a description of the licence text, not legal advice, and the setup.py author field reads FinRL LLC with a contact address at finrl.ai, so if you plan to redistribute a modified platform you should read the LICENSE file in full rather than relying on the badge. Upgrade cost is dominated by the dependency list. requirements.txt pins minimum versions for numpy, pandas, scikit-learn, lightgbm, xgboost, streamlit, alpaca-py, openai, bt, pydantic and torch, and the Dockerfile installs all of them at build time. A major bump in any one of pandas, pydantic or bt can break the config layer or the backtest engine, and there is no lockfile in the repository listing to pin the transitive graph.

## Three use cases the repository actually ships

The README documents three compositions, and they are worth separating because they demand different levels of trust. Use Case 1 compares allocation paradigms under the unified interface, which is the clearest demonstration of what the weight contract buys you. Use Case 2 pairs quarterly ML fundamental scoring with a DRL allocator over NASDAQ-100 names. Use Case 3 is the most elaborate: an adaptive multi-asset rotation strategy with three asset groups (Growth Tech, Real Assets, Defensive), a maximum of two active groups per week, group selection by information ratio against QQQ, intra-group ranking by residual momentum with a robust Z-score exception path, and a two-speed regime filter combining a 26-week trend with VIX plus a 3-day fast risk-off shock. The README's description of Use Case 3 is truncated mid-table at the risk controls row, so the exact risk overlay parameters are not documented in the README itself. If Use Case 3 is why you are here, treat the docs/ directory as required reading before you trust the defaults.

## Conclusion

Adopt FinRL-X if you already think in portfolio weights and want the same vector to survive the trip from backtest to broker, and if you are comfortable with a Beta-class codebase whose setup.py has been rewritten by hand. Do not adopt it as a turnkey live trading system: the README says nothing about order retries, reconciliation or rollback, and the execution layer only reaches Alpaca. Before committing, verify the .env.example keys against your own data providers and confirm that the ML_STOCK_SELECTION.md scoring path matches the universe you intend to trade, because the selection module is the one place where a silent change in inputs moves every downstream weight.

## FAQ

### Is machine learning good for trading?

FinRL-X does not answer this in the abstract; it makes the question testable. The README's Use Case 1 puts Equal Weight, Mean-Variance and Minimum Variance in the same table as a PPO/SAC DRL allocator and a KAMA timing overlay, all emitting the same weight vector, so the comparison is run under one backtest engine rather than across incompatible codebases.

### Can you explain how reinforcement learning works in trading?

In FinRL-X the learned component produces portfolio weights rather than buy and sell signals. The README lists a DRL Allocator under Use Case 1 that generates continuous weights via PPO or SAC, and those weights then pass through the timing adjustment and risk overlay stages before reaching the backtest engine or the Alpaca execution layer.

### How do I install finrl-trading?

The package is on PyPI as finrl-trading and the README targets Python 3.11 or later. A Dockerfile and docker-compose.yml are also provided at the repository root, with the compose file exposing port 8501 for the dashboard.

### Which brokers does FinRL-X support for live trading?

The README lists Alpaca only. The trading layer consists of alpaca_manager.py for multi-account integration, trade_executor.py for order management and risk controls, and performance_analyzer.py for P&L tracking, and no other broker integration is named.

### Is FinRL-X the same project as FinRL?

No. The README describes FinRL-X as succeeding the original FinRL framework with a modernized architecture, and the key structural change is that FinRL-X is organized around a target portfolio weight vector as the interface contract between strategy logic and execution.

### What Python version does FinRL-X require?

The README badge and setup.py classifiers both point at Python 3.11 and 3.12, and the Dockerfile builds from the python:3.11-slim base image. The README states Python 3.11 or later as the requirement.

## Sources

- [AI4Finance-Foundation/FinRL-Trading on GitHub](https://github.com/AI4Finance-Foundation/FinRL-Trading)
- [License: Apache-2.0](https://github.com/AI4Finance-Foundation/FinRL-Trading/blob/master/LICENSE)
- [Project website](https://ai4finance.org)
- [README](https://github.com/AI4Finance-Foundation/FinRL-Trading/blob/master/README.md)
- [Releases](https://github.com/AI4Finance-Foundation/FinRL-Trading/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/ai4finance-foundation-finrl-trading