Critical Bug: Backtest Module Crash Due to Gym Dependency and NumPy 2.0+ Incompatibility​

[Lixuyizhi]

🐛 Bug Description

When using the backtestmodule, the application crashes abruptly due to two interconnected issues

1. ​​Internal gym dependency​​: The backtest module implicitly relies on the gymlibrary, which is not explicitly declared as a dependency or handled gracefully if missing.
2. ​​NumPy 2.0+ incompatibility​​: The gymversion used (likely gym==0.26.2or earlier) does not support NumPy 2.0+

This results in a ​​hard crash​​ that terminates the entire Python process, including the IDE/kernel, without providing actionable error messages for end-users. It actually happen when i use the WeightStrategyBase class and run the entire programme with backtestmodule instead of workflow.

To Reproduce

Steps to reproduce the behavior:

1.Environment: Python 3.9.23 or 3.13 with NumPy 2.0+ installed. 2.Run a basic backtest script using QLib's backtestmodule(using WeightStrategyBase class ) 3.run the backtest with the 'backtest' like situation below : portfolio_metric_dict, indicator_dict = backtest( executor=executor_obj, strategy=strategy_obj, **backtest_config )

Expected Behavior

Expected​​: Backtest should run successfully or fail gracefully with a clear error message if dependencies are missing/incompatible.

​​Actual​​: Complete runtime crash with traceback

Screenshot

Gym has been unmaintained since 2022 and does not support NumPy 2.0 amongst other critical functionality. Please upgrade to Gymnasium, the maintained drop-in replacement of Gym, or contact the authors of your software and request that they upgrade. Users of this version of Gym should be able to simply replace 'import gym' with 'import gymnasium as gym' in the vast majority of cases. See the migration guide at https://gymnasium.farama.org/introduction/migration_guide/ for additional information.

and when i run the backtest the whole programme crashed. Then， i have to restart my IDE.

Environment

Note: User could run cd scripts && python collect_info.py all under project directory to get system information and paste them here directly.

• Qlib version:0.9.6
• Python version:3.9.23
• OS (Windows, Linux, MacOS):Windows
• Commit number (optional, please provide it if you are using the dev version):

Additional Notes

🛠️ ​​Suggested Fixes​​ ​​Replace Gym with Gymnasium​​:

gymis unmaintained since 2022 and incompatible with NumPy 2.0+ .

Migrate to gymnasium(maintained fork) by replacing import gymwith import gymnasium as gym.

​​Declare Explicit Dependencies​​:

Add gymnasium(or gymif retained) to QLib's requirements.txtor setup.py.

​​NumPy Version Locking​​:

Temporarily restrict NumPy to <2.0in dependencies until migration is complete.

​​Error Handling​​:

Add try-catch blocks around gymimports and initialize backtest dependencies lazily.

[SunsetWolf]

Hi, @Lixuyizhi Thank you for your attention to qlib. Could you create a PR to fix this issue? The expected solution is to upgrade gym to gymnasium.