FlagScale is one command line over Megatron, veRL and vLLM for many chips
FlagScale is a large model toolkit based on open-sourced projects.
At a glance
- What is it?
- FlagScale is the toolkit layer of the FlagOS stack, wrapping several upstream training, reinforcement learning and serving engines behind a single configuration and CLI so that the same model recipe can run on different accelerator vendors. Since v1.0.0 the hardware specific work has moved into separate plugin repositories, which changes what you get from this repository alone.
- Who is it for?
- Adopt FlagScale when you need to run the same model recipe on more than one accelerator vendor and you would rather change a config than rewrite your pipeline around each vendor's own entry points. Do not adopt it as a standalone trainer, because from v1.0.0 the chip-specific implementation lives in the separate plugin repositories, so you are adopting a coordination layer plus a plugin set.
- Can I use it commercially?
- Yes. Apache-2.0 is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository last received commits 6 days ago.
- What is it written in?
- Mainly Python, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on October 25, 2026, and from our analysis. They are not legal advice.
Editorial analysis
The coordination layer, not the engine
FlagScale is described as a large model toolkit based on open sourced projects, and the README positions it as a core component of FlagOS, a unified open-source AI system software stack.
The organising idea is stated as a principle: develop once, migrate across various chips. FlagOS is described as building an open technology ecosystem by integrating various models, systems and chips, breaking down barriers between different chip software stacks and reducing migration costs.
So the problem FlagScale addresses is not that no good training engines exist. Megatron-LM, veRL and vLLM all exist and all work. The problem is that each one has its own configuration format, its own launcher, its own hardware assumptions and its own way of describing a model, so moving a recipe from one vendor's stack to another is a port rather than a configuration change.
What FlagScale provides is a unified interface covering the complete lifecycle of large language models, multimodal models and embodied AI models, integrating multiple open-source backend engines under a single configuration and CLI interface. The workflows it names are model training, reinforcement learning and inference, with consistent operation across diverse chip vendors.
That is a layer of abstraction rather than a layer of new capability. The value, when it works, is that a team targeting several kinds of accelerator maintains one set of model configs and one set of launch scripts rather than one per vendor.
The project is Python, Apache 2.0 licensed, and the description in the package manifest credits the backing of the Beijing Academy of Artificial Intelligence. The releases are v2.1.0 from 2026-09-28, v2.0.0 from 2026-06-24 and v1.0.0 from 2026-03-26, with the last push on 2026-10-20.
The plugins carry the hardware work
The most important thing in the README is the 2026/03 announcement, and it changes what this repository is.
The v1.0.0 release is the first stable version, the codebase has been significantly refactored since v1.0.0-alpha.0, and the hardware-specific multi-chip support has been moved into plugin repositories such as TransformerEngine-FL and vllm-plugin-FL. Those plugins build on top of FlagOS, the unified open-source AI system software stack.
So the split is now clear. FlagScale holds the unified configuration, the CLI and the shared workflow, and the chip adaptation lives in the plugin repositories. If you are installing FlagScale alone, you get the coordination layer.
The mapping table is the clearest statement of the design:
| Task | FlagOS Plugin Projects | Upstream Projects | |------|----------------------|-------------------| | Training | Megatron-LM-FL, TransformerEngine-FL | Megatron-LM, TransformerEngine | | Reinforcement Learning | VeRL-FL | veRL | | Serve / Inference | vllm-plugin-FL | vllm |
The pattern is consistent. Each plugin takes an upstream project that is widely used and extends it to support multiple AI chips, providing hardware compatibility and runtime integration for training, reinforcement learning and inference. The upstream project keeps its own interface, and the plugin is where the vendor difference is absorbed.
Two other components complete the ecosystem. FlagCX is a scalable and adaptive cross-chip communication library, which matters when a model is sharded across different types of accelerator rather than across identical ones. FlagOS-Robo is infrastructure for embodied AI workloads.
There is a migration note for anyone arriving from an older version. If you are using or upgrading from a version earlier than v1.0.0-alpha.0, the README says to use the `main-legacy` branch, which will continue to receive critical bug fixes and minor updates for a period of time.
That branch is the older shape of the project, with the multi-chip support inside it rather than in plugins. So for a user, the choice between branches is the choice between the new plugin-based structure and the old self-contained one.
The CLI is Typer and Hydra with a YAML config tree
The package manifest describes the tool more precisely than the README does, and it is short:
[project]
name = "flagscale"
version = "1.0.0"
readme = "README.md"
license = {text = "Apache-2.0"}
requires-python = ">=3.10"
dependencies = ["typer>=0.9.0", "hydra-core"]
dynamic = ["optional-dependencies"]
[project.urls]
Homepage = "https://github.com/flagos-ai/FlagScale.git"
[project.scripts]
flagscale = "flagscale.cli:flagscale"
[tool.setuptools.packages.find]
include = ["flagscale*"]
[tool.setuptools.package-data]
"flagscale" = ["**/*.yaml", "**/*.yml"]The two runtime dependencies tell you the shape of the tool. Typer provides the command line, and Hydra Core provides the configuration system, and Hydra's composition model is what lets a config tree describe a model recipe and a chip-specific overlay separately and merge them at run time. That is exactly the mechanism a cross-vendor toolkit needs, because the difference between vendors is a set of values that overlay the common recipe.
The entry point is `flagscale.cli:flagscale`, so the command is `flagscale`. The package data entry ships every YAML and YML file inside the package, which is how the built-in configs travel with the installed distribution rather than needing to be fetched from the repository.
Two details are worth a note. The `dynamic = ["optional-dependencies"]` entry means the optional dependency groups are computed rather than listed, so the extras for a particular chip or a particular backend are assembled by the build. And `requires-python = ">=3.10"` is the floor, which matters for a project whose users run it on clusters with a fixed system Python.
The tool configuration is Ruff with a line length of 100, and the lint rules selected are the pycodestyle set, Pyflakes, pyupgrade, isort and a long list of flake8-bugbear checks.
One inconsistency is worth flagging for anyone pinning versions: the package manifest declares `version = "1.0.0"` while the published release tags are v2.1.0 and v2.0.0. The manifest version and the repository tag are not the same number, so the tag is the thing to track.
The example configs are the real documentation
The support list in the README is two tables, one for training and one for serving, and each row pairs a model with a configuration file path. That pairing is the documentation, because the config is where the abstraction actually lives.
For training, the listed models and their configs are DeepSeek-V3 with `examples/deepseek_v3/conf/train/16b_a3b.yaml`, Qwen2, 2.5 and 3 with `examples/qwen3/conf/train/235b_a22b.yaml`, Qwen2.5-VL with `examples/qwen2_5_vl/conf/train/7b.yaml`, QwQ with `examples/qwq/conf/train/32b.yaml`, LLaMA2 with `examples/llama2/conf/train/7b.yaml`, LLaMA3 and 3.1 with `examples/llama3/conf/train/70b.yaml`, LLaVA-OneVision with `examples/llava_onevision/conf/train/7b.yaml`, LLaVA1.5 with `examples/llava1_5/conf/train/7b.yaml`, Mixtral with `examples/mixtral/conf/train/8x7b.yaml`, RWKV with `examples/rwkv/conf/train/7b.yaml` and Aquila with `examples/aquila/conf/train/7b.yaml`.
For serving and inference the table lists DeepSeek-V3 with `examples/deepseek_v3/conf/serve/671b.yaml`, DeepSeek-R1 with `examples/deepseek_r1/conf/serve/671b.yaml`, Qwen2.5 with `examples/qwen2_5/conf/serve/72b.yaml` and Qwen3 with `examples/qwen3/conf/serve/8b.yaml`.
Two things can be read off these tables. The models span text-only and vision-language architectures, which matches the claim that the interface covers large language models, multimodal models and embodied AI models. And the configs are organised by model family and then by task, with `conf/train` and `conf/serve` as separate subtrees, so the same model has a training configuration and a serving configuration rather than one config with flags.
The naming inside the files is also meaningful. `16b_a3b.yaml` for DeepSeek-V3 refers to the model sizes, 16 billion parameters with 3 billion active, and `235b_a22b.yaml` is the same pattern for Qwen3. So the configs are per model size and architecture variant, not one generic template.
The `examples/` directory in the repository confirms the breadth. Alongside the models named in the tables there are directories for `aquila`, `cloud`, `deepseek_r1`, `deepseek_r1_distill_qwen`, `deepseek_v3`, `emu3`, `emu3.5`, `ernie45`, `flux_1_dev`, `glm5`, `gr00t_n1_5`, `grok2`, `kerv`, `kimi_k2`, `llama2`, `llama3`, `llava1_5`, `llava_onevision`, `minicpm_o_2.6`, `minicpm_v_4`, `mixtral`, `openjourney`, `pi0`, `pi0_5` and `qwen2`.
That list includes models from several organisations and several modalities, including image generation and embodied models, which is a wider surface than the support tables advertise.
The repository and the surrounding stack
The top level of the repository is conventional Python packaging with a few extras.
There is a `flagscale/` package directory, `run.py` at the root as a script entry point, `setup.py` alongside `pyproject.toml`, and `__init__.py` at the root. Then `examples/` for the model configs, `docs/` for the documentation including the getting started guide, the project change log and the Robo documentation, `tests/`, `tools/`, `docker/` and a `requirements/` directory.
There are also two project governance files worth naming. `MAINTAINERS.md` records who maintains which part, which for a project with many plugin repositories is the document that tells you who to ask. And `CODE_OF_CONDUCT.md` is present alongside a `.pre-commit-config.yaml`, which means formatting and lint hooks run before a commit lands rather than in a separate CI job.
The `.gemini/` directory at the root is an unusual entry, and it points at the direction this kind of project is taking: agent tooling configuration kept in the repository alongside the code.
The rest of the ecosystem is linked rather than vendored. The FlagOS plugins extend upstream frameworks, FlagCX handles cross-chip communication, and FlagOS-Robo provides the embodied AI infrastructure. So the dependency graph for a real deployment runs from a FlagScale config, through a plugin, into an upstream engine, and down onto a specific chip.
That layering is the whole point of the design and also its main operational cost, which is the subject of the next section.
Where the abstraction is fragile
There is a real limitation here, and it is structural rather than a missing feature.
FlagScale wraps upstream projects that keep moving. Megatron-LM, veRL and vLLM each release frequently and each change their own configuration, their own APIs and their own hardware support. A wrapper that exposes a unified interface has to keep tracking three moving targets, and when an upstream project makes a change that the wrapper has not absorbed yet, the failure appears as a configuration key the wrapper does not know or a code path that behaves differently from the upstream documentation.
That is why the plugin split matters so much. Because the hardware adaptation lives in the plugin repositories rather than in FlagScale, the part that has to track upstream changes is smaller and more focused, and a plugin can be updated independently of the toolkit.
The second limitation is the plugin coverage itself. A unified interface is only useful if there is an implementation for your hardware. The support list in the README covers models, not chips, and the mapping table lists the plugin projects rather than a matrix of plugin by chip. So the practical question before adopting is not whether FlagScale supports your model, but whether a plugin exists for the accelerator you have.
The third is the version story. v1.0.0 was announced as the first stable version in March 2026 with a significant refactor since the alpha, v2.0.0 followed in June, and v2.1.0 in September. The package manifest still declares 1.0.0. And the `main-legacy` branch exists for people upgrading from before v1.0.0-alpha.0. A project moving this fast, with a branch split and a manifest version that lags the tags, is a project where you should pin a specific release and read the change log for it, which the README links at `docs/CHANGELOG.md`.
The alternative approach is worth naming, because it is the honest comparison. Using the upstream projects directly, one per chip, with your own thin wrapper for the pieces that differ, gives you no abstraction to maintain and no compatibility surface to break, at the cost of writing and owning that wrapper yourself. FlagScale is that wrapper, already written, already covering a range of models and chips, and the trade is between the maintenance it saves you and the coupling it adds.
Editorial conclusion
Adopt FlagScale when you need to run the same model recipe on more than one accelerator vendor and you would rather change a config than rewrite your pipeline around each vendor's own entry points. Do not adopt it as a standalone trainer, because from v1.0.0 the chip-specific implementation lives in the separate plugin repositories, so you are adopting a coordination layer plus a plugin set. Verify first that a plugin exists for your hardware, that the example config for your model exists under `examples/`, that you are on the `main` branch rather than `main-legacy` unless you are upgrading from before v1.0.0-alpha.0, and that the version you install matches the release you read, with v2.1.0 published on 2026-09-28 while the package manifest still declares version 1.0.0.
Frequently asked questions
What is FlagScale?
It is a core component of FlagOS, a unified open-source AI system software stack, providing a unified interface across the whole lifecycle of large language models, multimodal models and embodied AI models. It integrates multiple open-source backend engines under a single configuration and CLI, supporting model training, reinforcement learning and inference with consistent operation across chip vendors.
How does FlagScale relate to Megatron-LM, veRL and vLLM?
Those are the upstream projects, and the FlagOS plugin projects extend them for multiple chips. The mapping is training through Megatron-LM-FL and TransformerEngine-FL, reinforcement learning through VeRL-FL, and serving through vllm-plugin-FL, with FlagCX providing cross-chip communication and FlagOS-Robo providing embodied AI infrastructure.
What changed in FlagScale v1.0.0?
It was released as the first stable version after a significant refactor since v1.0.0-alpha.0, and the hardware-specific multi-chip support moved out into separate plugin repositories such as TransformerEngine-FL and vllm-plugin-FL. Users on earlier versions are directed to the `main-legacy` branch, which continues to receive critical bug fixes and minor updates for a period.
How do I install and run FlagScale?
The package is built with setuptools, requires Python 3.10 or newer, and installs a `flagscale` command from `flagscale.cli:flagscale`. Its two runtime dependencies are typer for the command line and hydra-core for the configuration, and the YAML and YML files inside the package are shipped as package data so the built-in configs are available after installation. The Getting Started guide is at `docs/getting-started.md`.
Which models does FlagScale document configurations for?
The training support list covers DeepSeek-V3, Qwen2, 2.5 and 3, Qwen2.5-VL, QwQ, LLaMA2, LLaMA3 and 3.1, LLaVA-OneVision, LLaVA1.5, Mixtral, RWKV and Aquila, each with an example configuration file, and the serving table covers DeepSeek-V3, DeepSeek-R1, Qwen2.5 and Qwen3.
Official sources
Add this badge to your README
If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.
[](https://hysenlabs.com/projects/flagos-ai-flagscale)Was this useful?