MEALPY: a Python catalogue of population-based metaheuristics

What the library claims to be

MEALPY is described as the world's largest Python library, offering a comprehensive collection of recent meta-heuristic algorithms. The repository description calls it a collection of state-of-the-art metaheuristic algorithms in Python, with the topics spanning metaheuristics, nature-inspired algorithms and bio-inspired optimization.

The categories the README lists are long, and they overlap on purpose, which tells you how the collection grew. There are nature-inspired and bio-inspired algorithms, black-box optimization, global search optimizers, iterative learning algorithms, continuous optimization, derivative-free and gradient-free optimization, zeroth-order optimization, stochastic search optimization, and random search optimization. All of them fall under the category of population-based metaheuristics.

The numbers are specific. The README states a total of 233 algorithms, made up of 206 official ones, which it describes as original, hybrid and variants, and 27 developed by the author. The library is free software under the MIT licence, it supports Python 3.8 and newer, and its dependencies are numpy, scipy, pandas, matplotlib and tqdm.

The stated goals are to implement all classical as well as the state-of-the-art nature-inspired algorithms, to create a simple interface so researchers can reach an optimisation algorithm quickly, and to share knowledge of the optimisation field without a fee.

The repository is not archived and the last push was on 2026-09-23. The release history is v3.0.3 from 2025-08-16, v3.0.2 from 2025-05-30 and v3.0.1 from 2023-11-05, while the release badge in the README header advertises 3.1.0, so the badge and the tag list have drifted apart.

The typed decision variables, which is the interface's real idea

Before any example, the README spends a section on decision variables, and this is the part of the API worth understanding.

Instead of passing a raw numpy array of bounds, you declare variables with typed classes, and the library uses that description to build the search space.

The classes are `FloatVar` for a continuous problem, with syntax `FloatVar(lb=(-10., )*7, ub=(10., )*7, name="delta")`. `IntegerVar` covers linear, integer, nonlinear and quadratic and mixed integer programming problems with the same lower and upper bound shape. `StringVar` takes valid sets as tuples of tuples, for example `StringVar(valid_sets=(("auto", "backward", "forward"), ("leaf", "branch", "root")), name="delta")`, and is aimed at machine learning and AI optimisation problems. `BinaryVar` and `BoolVar` both take a count of variables, `BinaryVar(n_vars=11, name="delta")` and `BoolVar(n_vars=11, name="delta")`, and are also for machine learning and AI optimisation. `PermutationVar` takes a single valid set, `PermutationVar(valid_set=(-10, -4, 10, 6, -2), name="delta")`, for combinatorial optimisation, and `CategoricalVar` follows the same shape as `StringVar`.

This is a real improvement over the usual array-of-bounds interface, because it means the algorithm knows whether it is searching over integers or categories, and it means the type of the answer is defined by the variable you declared.

The README's framing is that understanding your specific problem and its desired solution can help you select the most appropriate approach, and the table is a guide to defining your search space effectively.

Installing it and checking the version

Installation is the ordinary set of PyPI variants.

The stable release is:

$ pip install mealpy --upgrade

The alpha or beta version is a pinned pre-release, `pip install mealpy==2.5.4a6`, the pre-release from source is a clone followed by `python setup.py install`, and the development version straight from GitHub is `pip install git+https://github.com/thieu1995/mealpy`.

After installation, the README suggests a check that the version came through and that the optimiser registry is populated:

$ python
>>> import mealpy
>>> mealpy.__version__

>>> print(mealpy.get_all_optimizers())
>>> model = mealpy.get_optimizer_by_name("OriginalWOA")(epoch=100, pop_size=50)

Two things are visible in those four lines. There is a name-based registry, `get_optimizer_by_name`, and the names carry a provenance prefix, so `OriginalWOA` is the original whale optimisation algorithm rather than a hybrid or a variant, and the same naming distinguishes the 27 developed algorithms from the 206 official ones. And the constructor takes `epoch` and `pop_size` directly, which are the two parameters that matter for a population-based method, the number of generations and the size of the population.

The `setup.py` shows the versioning mechanism, which is a detail worth knowing: the version is read out of `mealpy/__init__.py` with a regular expression looking for the `__version__` assignment, and the build fails with a clear error if it cannot find it. The package metadata also carries a long keyword list, which tells you what the author wants the project found for.

What the library says you can do with it

The goals section lists what the library is for, and the list is broader than running an optimiser.

You can analyse the parameters of meta-heuristic algorithms. You can perform qualitative and quantitative analysis of algorithms. You can analyse the rate of convergence of algorithms. You can test and analyse the scalability and the robustness of algorithms. You can save results in various formats, namely csv, json, pickle, png, pdf and jpeg. And exporting and importing models can also be done with Mealpy.

Then the catch-all, to solve any optimization problem.

The point worth making is that the analysis and export features are not decoration. If you are choosing an algorithm, or defending a choice, the artefact you need is a convergence curve over multiple runs with a comparison, and that is what the png and pdf output and the convergence analysis are for. The pickle and json export exist so a trained model can be reloaded rather than recomputed.

The example directory backs this up. There is `run_all_parameters.py`, `run_multi_functions.py`, `run_multi_functions_multi_trials.py`, `run_multi_functions_multi_trials_parallel.py`, `run_multi_functions_parallel.py` and `run_multitask.py`, which between them cover single runs, several objective functions, several trials, and both parallel and multitask execution. There is `run_tuner.py` for hyperparameter tuning and `build_new_optimizer.py` for adding your own, plus `applications/` and `optimizers/` subdirectories and a notebook for the multitask case.

The multi-trial script in particular is the one to reach for first, because a stochastic optimiser on one run is not a measurement.

The citation request, and the paper behind it

The README asks you to include citations if you plan to use the library, and the bibtex block it gives is a good indication of what this project is for.

The first is the MEALPY paper itself, MEALPY: An open-source library for latest meta-heuristic algorithms in Python, by Van Thieu and Mirjalili, in the Journal of Systems Architecture in 2023, with the DOI 10.1016/j.sysarc.2023.102871. The Zenodo badge points at the same work, and the `CITATION.cff` file in the repository root does the same job for tools that read it.

The second citation is a groundwater level modelling paper using Augmented Artificial Ecosystem Optimization, and the third is a comprehensive comparison of recent meta-heuristic algorithms for a streamflow time series forecasting problem.

The inclusion of the comparison paper is the useful signal. A library that exists to collect algorithms has an obvious credibility problem, and the answer to that problem is not a longer algorithm list but a paper that compares them on a common benchmark. The third citation is that paper.

For an adopter, that means the evaluation of the library is not something you have to do from scratch. The comparison in the applied soft computing paper is the closest thing to a benchmark table for the collection, and it is the first thing to read before picking an algorithm.

The project structure, and what the examples directory implies

The top level of the repository is conventional for a Python library with documentation and a paper behind it.

There is the `mealpy/` package itself, `tests/`, `docs/` for the readthedocs site, `examples/`, `scripts/`, and the packaging files, `setup.py`, `MANIFEST.in` and `LICENSE`. There is a `ChangeLog.md` that the README points to for detailed updates on each version, a `CITATION.cff`, a `CODE_OF_CONDUCT.md`, a `.flake8` configuration, and a `.readthedocs.yaml`.

The `examples/` directory is worth a second look because its file names describe the shape of the library's testing surface. The `applications/` directory holds the real-world problems, and the `optimizers/` directory holds per-algorithm examples, with `utils/` holding shared helpers. The runner scripts are named for what they vary: `run_simple_function.py` for the basic case, `run_multi_functions.py` for several objectives, `run_multi_functions_multi_trials.py` when you need statistics, and the parallel variants of both.

`build_new_optimizer.py` is the one that tells you the library is extensible rather than fixed, and it pairs with the plugin-oriented topics in the repository metadata and the count of developed algorithms that are not official ones.

The `docs/` directory and the readthedocs badge are what make the library usable by someone who did not write it, and the change log is the thing to read when a version bump changes the default behaviour of an optimiser, which for a collection of 233 algorithms is likely to be the main upgrade risk.

Where MEALPY is the wrong choice

The first wrong case is a production system that needs one algorithm done well. MEALPY gives you a catalogue and a uniform interface, and choosing from a catalogue of 233 is a research task, not a configuration change. If you already know you want a particle swarm or a differential evolution, and you know your problem, a single focused implementation with a tuned parameterisation is smaller and better.

The second wrong case is a team that cannot evaluate stochastic results. Every one of these algorithms is randomised, so a single run tells you almost nothing about the algorithm and a comparison of single runs tells you even less. If you have no budget for the multi-trial scripts and the convergence analysis, the library's output will be a table of numbers that look like results.

The third is a project with a hard latency or memory budget. A population-based method with 50 individuals over 100 epochs is thousands of objective evaluations, and the library is a research tool rather than something tuned for a production path.

The fourth is a team that wants a guarantee. None of these methods guarantees an optimum, and the README does not pretend otherwise, but a catalogue of 233 nature-inspired algorithms can create the impression that one of them will find the answer, and there is no theoretical reason to prefer one over another without benchmarking.

The fifth is an organisation that needs reproducibility under a licence review. The licence is MIT and the citation is requested rather than required, and the algorithms themselves come from a literature with many independent implementations, so a result you get here may not match one you get from the original paper's code.

What MEALPY is good at is being the fastest way to try ten plausible optimisers on a problem you have not modelled carefully yet, and the multi-trial and convergence tooling is what makes that useful rather than merely fast.

Editorial conclusion

MEALPY suits a researcher or engineer who needs to try a spread of nature-inspired optimisers against one problem without writing each of them, and who will then benchmark them properly on their own objective. It does not suit a production service that needs one algorithm done well, since a catalogue gives you the search space and not the answer, and it does not suit a team that cannot evaluate whether any of the 233 results is better than a tuned baseline. Before adopting it, read the journal paper the project asks you to cite, because it is the only place the algorithms are compared rather than merely listed, and check the `examples/` directory for the multi-trial and parallel scripts, since a single run of a stochastic optimiser tells you very little.

Frequently asked questions

Official sources

1. License: MIT
2. Project website
3. README
4. Releases
5. thieu1995/mealpy on GitHub