The extensive development of hydropower projects has notably changed the ecohydrological conditions of fish habitats, affecting fish behavior, including habitat usage and migration, to varying extents. Understanding fish migration dynamics is essential for quantitatively assessing the impact of ecological restoration measures on migratory fish. However, no model has yet demonstrated sufficient accuracy to be considered valuable in ecological restoration engineering. To address this issue, in this article, a coupled machine-learning-individual-based model (ML-IBM) consisting of random forest (RF) and Eulerian–Lagrangian–agent method (ELAM) is constructed for predicting fish migration, aiming to find effective fish passage solutions before implementation. In this study, the passage data of ya-fish (Schizothorax prenanti) in vertical slot fishways (VSFs) is compiled to train ML-IBM to simulate fish migration in fish passage facilities. In movement prediction, the accuracy of swimming behavior classification reaches 83.4 %, and the R² for swimming speed regression exceeds 0.77. Compared with other state-of-the-art migration dynamic models, the proposed ML-IBM achieves the lowest root mean square error (RMSE) of 7.35 and a mean absolute error (MAE) of 6.26 in migration simulation results. Further, RF is used to quantitatively calculate the importance of input features. The contributions of each feature are analyzed and discussed from a hydrodynamic perspective, with the importance ranked as follows: flow velocity (FV) > turbulent kinetic energy (TKE) > total hydraulic strain (THS). This approach enhances the interpretability of the model and provides further insights into the mechanism of fish migration. The results presented in this study have significant implications for informing decision-making in the management of living resources and guiding engineering design processes.