Install FinRL 0.3.7: The Mistake Everyone Makes First

Here’s what kills most FinRL installs: running pip install git+https://github.com/AI4Finance-Foundation/FinRL.git before installing system dependencies. SWIG errors. Box2D failures. Missing C++ compilers. The install dies. You Google. You try workarounds. An hour vanishes.

Correct sequence? System packages first, then pip. But there’s a second decision nobody mentions upfront: which FinRL should you even install? The original (education-focused) or FinRL-X (production-ready)?

Which FinRL: Original vs. FinRL-X

Are you experimenting with RL concepts, or building a trading system you might deploy?

FinRL (original) – For “education, benchmarking, and research prototyping” (per the official GitHub). Three-layer architecture: data, environment, agent. Jupyter notebooks walk through stock trading with DRL algorithms like PPO and SAC. Great for learning. Not designed for live trading at scale.

FinRL-X / FinRL-Trading – The 2026 upgrade. “AI-native, modular, and production-oriented” (FinRL-X paper, arXiv:2603.21330, March 2026). Weight-centric architecture. Backtesting engine built in. Alpaca API for paper/live trading. Pydantic config management. The GitHub README: “Recommended for new users: Start with FinRL-X / FinRL-Trading if you are building modern or production-oriented trading systems.”

Most tutorials default to the original. This guide covers both. If you’re unsure, skim the FinRL-X examples first – you might skip the original entirely.

System Requirements

Python 3.12+ breaks FinRL. GitHub issue #1132: cvxpy throws “use_2to3 is invalid.” Stick to 3.9-3.11 (as of early 2026).

Install FinRL (Original) – Step-by-Step

Ubuntu

System dependencies first. You need cmake, OpenMPI, SWIG, dev headers (official docs):

sudo apt-get update && sudo apt-get install cmake libopenmpi-dev python3-dev zlib1g-dev libgl1-mesa-glx swig

Virtual environment (Python 3.9):

python3.9 -m venv finrl_env
source finrl_env/bin/activate

Install FinRL. The official recommendation? Unstable dev version from GitHub, not PyPI. “We are still actively updating the FinRL repository”:

pip install git+https://github.com/AI4Finance-Foundation/FinRL.git

Pulls dependencies: Stable Baselines 3, Gym, yfinance, stockstats, pyfolio. Box2D builds from source – if it fails, see Common Errors.

macOS

Homebrew for SWIG:

brew install swig

Then:

python3.9 -m venv finrl_env
source finrl_env/bin/activate
pip install git+https://github.com/AI4Finance-Foundation/FinRL.git

Apple Silicon (M1/M2)? Rosetta warnings might pop up. FinRL works natively, but some older dependencies (pyfolio) may install x86 wheels.

Windows 10/11

SWIG: the problem. pip install swig does not install the actual SWIG executable – placeholder package only. You need to:

1. Download SWIG from swig.org (Windows binary)
2. Extract to C:swigwin-4.x.x
3. Add C:swigwin-4.x.x to PATH
4. Restart terminal

Anaconda Prompt or PowerShell:

python -m venv finrl_env
finrl_envScriptsactivate
pip install git+https://github.com/AI4Finance-Foundation/FinRL.git

GitHub issues #654, #419: this PATH step is the #1 Windows gotcha.

Box2D won’t build? Try WSL2 (Windows Subsystem for Linux). Install Ubuntu 22.04 in WSL2, follow the Ubuntu steps. Sidesteps SWIG PATH headaches. Cleaner Python environment.

Install FinRL-X (Production Stack)

Fewer dependency nightmares. No Box2D required. Clone and install:

git clone https://github.com/AI4Finance-Foundation/FinRL-Trading.git
cd FinRL-Trading
python3 -m venv venv
source venv/bin/activate # Windows: venvScriptsactivate
pip install -r requirements.txt

Paper trading config (optional). Copy env file:

cp .env.example .env

Edit .env, add Alpaca API credentials (free at alpaca.markets). Backtesting only? Skip this.

First-Time Config & Verification

FinRL original: download tutorial notebooks.

git clone https://github.com/AI4Finance-Foundation/FinRL-Tutorials.git
cd FinRL-Tutorials
jupyter notebook

Open FinRL_StockTrading_NeurIPS_2018.ipynb. Run first cell. If finrl imports without errors, you’re set. Notebook downloads DOW 30 stock data, trains 5 DRL agents (A2C, DDPG, PPO, TD3, SAC), backtests them. 10-20 minutes on a laptop.

FinRL-X: quick backtest.

./deploy.sh --strategy adaptive_rotation --mode backtest --start 2023-01-01 --end 2024-12-31

Downloads data, runs strategy, outputs metrics (Sharpe ratio, max drawdown). Completes? Install verified.

Common Install Errors & Fixes

Error:command 'swig' failed: No such file or directory

SWIG missing or not in PATH. Ubuntu: sudo apt-get install swig. Mac: brew install swig. Windows: download binary, add to PATH (see above).

Error:AttributeError: module '_Box2D' has no attribute 'RAND_LIMIT_swigconstant'

Box2D version mismatch. Official workaround (docs):

pip install box2d box2d-kengz

Forces compatible version.

Error:error in cvxpy setup command: use_2to3 is invalid

Python 3.12. Downgrade to 3.11 or 3.9. FinRL’s PyPortfolioOpt dependency (needs cvxpy) doesn’t support 3.12 yet (as of early 2026).

Warning:UserWarning: Module "zipline.assets" not found

Ignore it. Docs confirm: “installation is still successful.” FinRL doesn’t require zipline.

Data download fails silently (“No data found for this date range”)

China? YahooFinance is blocked. Docs: “VPN is needed if using YahooFinance in china.” Connect to VPN, re-run data download cell.

Why Box2D exists (and why you’ll never use it)

Box2D is an OpenAI Gym dependency. Classic RL benchmarks (LunarLander, BipedalWalker) need it for physics simulation. Stock trading? You’ll never touch those environments. The dependency exists because FinRL inherits Gym’s full environment set – even though financial RL only uses the market simulators.

FinRL-X dropped Box2D entirely. For financial RL only, that’s reason enough to consider FinRL-X over the original.

Uninstall / Cleanup

Remove FinRL:

pip uninstall finrl elegantrl pyfolio stable-baselines3 box2d-py

Delete venv:

rm -rf finrl_env # or deactivate + delete folder on Windows

FinRL-X? Delete the cloned repo. Self-contained.

The GitHub vs. PyPI reality

Official docs say install the “unstable development version” via pip install git+https://.... Why not PyPI? FinRL development happens on GitHub. PyPI lags behind. Latest PyPI: 0.3.7. The repo? Commits from the past month (as of early 2026). Bug fixes and recent features live on GitHub. Always install from GitHub for financial RL work.

FAQ

Can I use FinRL with Google Colab?

Yes. Colab has most dependencies. Run !pip install git+https://github.com/AI4Finance-Foundation/FinRL.git in a cell. Box2D fails? !apt-get install swig first, retry.

Does FinRL support cryptocurrencies or only stocks?

Both. FinRL includes a crypto trading environment (FinRL_Crypto) that pulls data from exchanges via CCXT. Tutorial notebook: FinRL_MultiCrypto_Trading.ipynb. Trades top 10 cryptos by market cap. Data pipeline differs (CCXT not yfinance), but DRL training loop? Identical. One caveat: CCXT rate limits hit hard if you’re pulling high-frequency data – I burned through my free tier testing 1-minute candles for BTC.

What’s the difference between FinRL, FinRL-Meta, and FinRL-X?

FinRL: original framework (education + research). FinRL-Meta: environment/benchmark layer – market simulators and datasets for testing strategies. Part of the ecosystem but installed separately. FinRL-X (FinRL-Trading): 2026 production rewrite. Modular. Weight-centric architecture. Live trading support. Starting fresh in 2026? Use FinRL-X unless you specifically want the tutorial notebooks from the original.

Clone the repo you chose. Run install commands for your OS. Train your first agent. Adaptive rotation backtest (FinRL-X) or NeurIPS 2018 stock trading notebook (original). Both: under 20 minutes.