MobileModels: a curated index of phone model names and their marketing names

What MobileModels actually indexes

MobileModels is a text dataset of phone model codes and the names those phones are sold under. The README describes the project as a summary of models each manufacturer has put on the market together with their corresponding marketing names. Model codes are what appear in firmware, IMEI databases and carrier systems. Marketing names are what appear on a store page. The gap between the two is the problem this repository addresses.

The scope is broader than phones. The brand table lists tablets, watches, TWS earbuds, smart TVs, set-top boxes and even Macs with Apple Silicon under apple_all. It is aimed at people who need to resolve an identifier: a developer matching a user agent string, a repair technician checking which retail name a board belongs to, or a compliance reviewer confirming a device was sold in a particular market.

What it is not is a specification or pricing source. There is no mention of launch dates, chipsets, camera sensors or prices in the README. Anyone arriving from a search for phone model and price will not find that here.

How the brand files and China/global split work

The repository is organised as a directory tree. Top-level entries are CHANGELOG.md, CHANGELOG_en.md, LICENSE.txt, README.md, README_en.md, brands/ and misc/. Each brand has one or more files under brands/, and the README's table is the index to them.

The split between China and global variants is the design decision that matters most. Xiaomi appears as xiaomi.md, xiaomi_cn.md and xiaomi_en.md. Apple appears as apple_all.md, apple_all_en.md and apple_cn.md. Samsung has samsung_cn.md and samsung_global_en.md. The same physical device can carry a different model suffix per market, so a single merged table would be ambiguous. Keeping the files separate lets you match a code to the market it was sold in.

The table also marks coverage honestly. Each row carries a three-state indicator: included, partially included, or not included. Huawei's China file is marked as partial, as are HONOR's, OPPO's and realme's. That marker is the first thing to check before trusting a lookup, because a missing row may mean the model does not exist in that market or simply that the maintainer has not catalogued it yet. The README also points to misc/early-huawei-models.md and misc/early-samsung-models.md for older devices that fall outside the main files.

Getting the files and doing a first lookup

There is no package to install. The data lives in the repository, so the practical setup is to fetch it from GitHub. The README gives no install command and no documented lookup command; it only links the brand files, the online browser at https://mobilemodels.kevinh.wang/ and the separate CSV repository at https://github.com/KHwang9883/MobileModels-csv.

A first real use is resolving a model code to a retail name. Open the file for the brand and market you care about, for example brands/xiaomi_cn.md for China-market Xiaomi devices or brands/apple_all.md for the Apple range, and read the row for your code. The README's table is the map from brand to file, so start there if you are unsure which file applies.

If the code appears, the surrounding row gives you the marketing name. If it does not, check the coverage marker for that brand in the README before concluding the device is unknown, since several brands are explicitly partial. The README does not describe the CSV schema, so treat the Markdown files as the primary source until you have inspected the CSV output yourself.

Where the coverage markers will let you down

The partial-coverage flags are not cosmetic. HONOR's China file covers phones, tablets, laptops, smart screens and wearables but is marked partial, and the global English file is partial as well. OPPO's China file only covers models from 2018 onward under the newer naming scheme. realme's China file is partial. Huawei's global English file is marked partial on both the China and overseas columns.

That means a negative result is weak evidence. If you are building a validation rule that rejects unknown model codes, a code absent from a partial file may be a legitimate device the maintainer has not added. You need a fallback path, or you need to restrict the rule to brands marked as fully included, such as Apple, Xiaomi, OnePlus, MEIZU, Black Shark and Sony.

There is a second limitation in the scope itself. The dataset maps codes to names. It does not carry the attributes that most device-detection systems need, such as release year, screen size or chipset. If your matching logic depends on those, MobileModels can only supply the naming half of the join.

The project history also shows churn in the delivery format. The document version stopped being maintained in July 2019, the CSV and scripts moved to a separate repository in March 2024, and a bootloader and kernel-source summary added in April 2022 is marked as no longer updated. Anyone depending on a specific file layout should expect it to move again.

MobileModels compared with device-detection libraries

The closest alternative in practice is a device-detection library such as those that parse user agent strings and return a device name. The difference in approach is the direction of the mapping. A detection library starts from a string observed at runtime and guesses the device. MobileModels starts from a model code and gives you the manufacturer's own naming, compiled by hand from sources like the MIIT platform, CMIIT ID lookups, Wi-Fi Alliance and Bluetooth qualification listings, Google Play's supported devices list and vendor open source release centres, all of which are listed in the README's reference section.

That makes MobileModels better for offline reconciliation and worse for live traffic classification. It has no runtime component, no API and no update mechanism you can call from an application. The CSV repository is the closest thing to a machine-readable feed, and the README does not document its schema or refresh cadence beyond the note that GitHub Actions updates it.

A second alternative is the manufacturer's own documentation, which is authoritative but scattered across support sites and often only available in one language. MobileModels adds value precisely by normalising those sources into one file per brand and market, and by keeping an English variant for many brands.

Maintenance, licence and upgrade cost

The repository is not archived, and the last push was on 2026-09-22. There are no releases, so there is nothing to pin. Updates arrive as commits to the Markdown files and to the changelogs, CHANGELOG.md and CHANGELOG_en.md, which the README points to as the update log. Upgrading means pulling the branch and diffing the brand files you depend on. Since the data is plain text, a diff is readable, but it also means there is no version number to record in a lockfile.

The licence is CC BY-NC-SA 4.0, stated in the README and in LICENSE.txt. Two implications are worth noting before you build on it. The NonCommercial clause restricts commercial use of the material, and the ShareAlike clause means adaptations must carry the same licence. Attribution is required. This is not legal advice, and the exact boundary of commercial use in your context is a question for your own counsel.

The practical upgrade cost is low in engineering terms and non-trivial in process terms. Nothing compiles, so there is no build to break. What you do need is a way to detect when a brand file changes and to re-check any rows you have cached, because a partial file can gain rows at any time.

Editorial conclusion

MobileModels suits developers, repair shops and compliance teams who need a model code mapped to a retail name and can accept CC BY-NC-SA 4.0 terms. It is the wrong tool if you need launch dates, prices or specs, since the README describes only model and marketing-name data. Before adopting it, open brands/xiaomi.md and brands/xiaomi_cn.md and check whether the rows for the devices you care about are marked complete, partial or absent, and confirm the CSV repo's update path if you plan to automate ingestion.

Frequently asked questions

Official sources

1. Issues
2. KHwang9883/MobileModels on GitHub
3. Project website
4. README