ultravin

An extremely fast, fully offline NHTSA vPIC VIN decoder, written in Rust.

VINs decoded per second: ultravin 81,948 batched on 4 cores / 25,175 single-core vs corgi v3 83, corgi v2 33, NHTSA MSSQL 22.5, NHTSA Postgres 19.5
_{VINs decoded per second over a random corpus, single sequential caller — ultravin also batches across cores.}

⚡️ ~0.042 ms per decode — orders of magnitude faster than the NHTSA SQL procedures (corgi, Postgres, MSSQL)
🦀 Pure Rust core, shipped as a Python library
📦 The entire vPIC vehicle database baked into the wheel
🔌 Fully offline — no network, no database, no data files at runtime
🎯 Byte-for-byte parity with vPIC's spVinDecode, verified across every decodable VIN — except documented vPIC defects, which ultravin deliberately does not reproduce (the registry, evidence)
🐍 Installable via pip, with a CLI and a library API
🧵 Batches in parallel to ~82,000 VIN/s on 4 cores
🗃️ Parquet in, parquet out — decodes a dataset of any size in the memory of one chunk

ultravin is a faithful port of NHTSA's spVinDecode — the SQL procedure behind vPIC — reimplemented in Rust and verified against the reference Postgres implementation. Because the vehicle database ships inside the binary, decoding needs no network, no database server, and no data files. Install it and decode.

Getting Started

Installation

uv add ultravin

Prebuilt wheels require Python 3.10+ and nothing else — the data ships inside the wheel.

Usage

From Python:

import ultravin

r = ultravin.decode("1HGCM82633A004352")

r["model_year"]  # 2003
r["wmi"]  # '1HG'
r["check_digit_valid"]  # True
r["error_codes"]  # [0]

# `elements` is the full decoded attribute list, one dict per attribute:
r["elements"][0]  # {'variable': 'Make', 'value': 'HONDA', 'source': ..., …}

decode(vin) returns a dict with keys vin, wmi, descriptor, model_year, error_codes, check_digit_valid, corrected_vin, and elements — a list of per-attribute dicts (group_name, variable, value, element_id, source, …). Decode many at once with decode_batch:

results = ultravin.decode_batch(["1HGCM82633A004352", "5YJ3E1EA7JF000000"])

If you already know a vehicle's model year, pass it — the same optional hint the vPIC API calls modelyear. It matters for pre-2010 vehicles, where the VIN's year character is ambiguous (A means 1980 or 2010): the hinted year gets its own decode pass that competes against the VIN-derived one, and a hint that contradicts the decoded year adds error code 12.

ultravin.decode("1HGCM82633A004352", year=1995)  # decodes as a 1995
ultravin.decode_batch(vins, years=[2011, None, 1987])  # one entry per VIN

If you only want the values, pass flat=True and skip the per-attribute dicts entirely — ~2× faster end to end. Decoding is no longer the expensive part; building ~615 dict entries per VIN is:

r = ultravin.decode("1HGCM82633A004352", flat=True)

r["attributes"]["Make"]  # 'HONDA'
r["attributes"]["Model"]  # 'Accord'

flat=True replaces elements with attributes, a single variable -> value mapping (header keys are unchanged), and works the same on decode_batch, decode_json and decode_batch_json. Two things to know:

Values are str, except the free-text note fields listed in ultravin.MULTI_VALUED, which are always list[str] — those are the only vPIC elements allowed to repeat within one decode, and each row is a separate note rather than a competing value.
It keeps the value and drops the provenance. If you need to know where a value came from (source — over half of all rows are vehicle-type defaults rather than something the VIN encodes), or the raw vPIC attribute_id, use the default shape.

ultravin.ELEMENTS maps each variable name to its static metadata (element_id, group_name, data_type, …). Pin to element_id if you need a key that survives NHTSA renaming a variable between data releases.

From the command line:

ultravin decode 1HGCM82633A004352          # human-readable table
ultravin decode 1HGCM82633A004352 --json   # full JSON
ultravin decode 1HGCM82633A004352 --flat   # values only, no provenance
ultravin decode-batch vins.txt --json      # one VIN per line
ultravin version

Datasets

For bulk work there is a parquet door — parquet in, parquet out, without a single row ever becoming a Python object:

import ultravin

rows = ultravin.decode_parquet("registrations.parquet", "decoded.parquet", codes=["Make", "Model"])

rows  # 4812004 — the rows written, not the rows themselves

The VIN column is found by name (vin, case-insensitively) and then by sniffing the leading rows, as is the optional caller-year column (year, model_year, …); pass vin=/year= to name them outright. Pick the projection with codes= (vPIC variable names) or ids= (element_ids, the key that survives NHTSA renaming a variable), or omit both for every publicly decodable element. The output holds the VIN and caller year passed through, then decoded_model_year (named so it cannot collide with an input column called model_year), then one column per projected element — string, int64 or float64 following vPIC's own data_type, with an empty value written as null. A source that is a directory works wherever a file does: every *.parquet in it is read in sorted order as one stream.

Rows stream through in batch_size chunks with the GIL released, so peak memory is one chunk no matter how large the source is. Leave the destination out to get the whole decode back as {column: [values]} (small inputs only), or iterate ParquetBatchIter to stream it a chunk at a time:

for chunk in ultravin.ParquetBatchIter("registrations.parquet", ids=[26], batch_size=100_000):
    chunk["Make"][:2]  # ['HONDA', 'FORD']

Reading and writing parquet is the same Rust as the decoding, so this needs no pyarrow and no other install.

From the command line:

ultravin decode-parquet registrations.parquet decoded.parquet --codes Make,Model
ultravin decode-parquet parts/ decoded.parquet --ids 26,28 --vin chassis_no

Benchmarks

How many VINs each engine decodes per second, single sequential caller, over an identical random corpus of 5,000 valid VINs (measured over 60 s; Apple Silicon, batched across 4 cores):

engine	VIN/s	vs ultravin (1 core)
ultravin — batched, 4 cores	81,948	~3.3× faster
ultravin — 1 core	25,175	1×
corgi v3 — `@cardog/corgi` (binary index)	~83	~303× slower
corgi v2 — `@cardog/corgi` 2.0.1 (SQLite)	~33	~763× slower
NHTSA MSSQL — `spVinDecode` (SQL Server)	22.5	~1,119× slower
NHTSA Postgres — `spvindecode`	19.5	~1,291× slower
NHTSA vPIC web API — public rate limit	~10	~2,518× slower

ultravin runs in-process with the database embedded — no server, no round-trip. The corgi figures are derived from its project's published per-VIN latency (~12 ms v3 / ~30 ms v2, not re-measured here). The NHTSA Postgres and MSSQL oracles run the unmodified spVinDecode over localhost; MSSQL is SQL Server under amd64 emulation on Apple Silicon, so its number understates native hardware — ultravin is still ~1,119× faster. The NHTSA vPIC web API row is its published ~10 req/s rate limit, not a decode time — a hard ceiling regardless of hardware. Methodology and reproduction: docs/BENCHMARKS.md.

License

MIT. The embedded NHTSA vPIC data has its own provenance — see NOTICE.

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

ultravin-1.1.0.tar.gz (21.2 MB view details)

Uploaded Aug 21, 2026 Source

Built Distributions

If you're not sure about the file name format, learn more about wheel file names.

The dropdown lists show the available interpreters, ABIs, and platforms. Enable javascript to be able to filter the list of wheel files.

ultravin-1.1.0-cp310-abi3-win_arm64.whl (25.2 MB view details)

Uploaded Aug 21, 2026 CPython 3.10+Windows ARM64

ultravin-1.1.0-cp310-abi3-win_amd64.whl (25.7 MB view details)

Uploaded Aug 21, 2026 CPython 3.10+Windows x86-64

ultravin-1.1.0-cp310-abi3-win32.whl (25.2 MB view details)

Uploaded Aug 21, 2026 CPython 3.10+Windows x86

ultravin-1.1.0-cp310-abi3-musllinux_1_2_x86_64.whl (25.9 MB view details)

Uploaded Aug 21, 2026 CPython 3.10+musllinux: musl 1.2+ x86-64

ultravin-1.1.0-cp310-abi3-musllinux_1_2_i686.whl (25.9 MB view details)

Uploaded Aug 21, 2026 CPython 3.10+musllinux: musl 1.2+ i686

ultravin-1.1.0-cp310-abi3-musllinux_1_2_armv7l.whl (26.1 MB view details)

Uploaded Aug 21, 2026 CPython 3.10+musllinux: musl 1.2+ ARMv7l

ultravin-1.1.0-cp310-abi3-musllinux_1_2_aarch64.whl (25.6 MB view details)

Uploaded Aug 21, 2026 CPython 3.10+musllinux: musl 1.2+ ARM64

ultravin-1.1.0-cp310-abi3-manylinux_2_31_riscv64.whl (25.8 MB view details)

Uploaded Aug 21, 2026 CPython 3.10+manylinux: glibc 2.31+ riscv64

ultravin-1.1.0-cp310-abi3-manylinux_2_28_aarch64.whl (25.4 MB view details)

Uploaded Aug 21, 2026 CPython 3.10+manylinux: glibc 2.28+ ARM64

ultravin-1.1.0-cp310-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (25.6 MB view details)

Uploaded Aug 21, 2026 CPython 3.10+manylinux: glibc 2.17+ x86-64

ultravin-1.1.0-cp310-abi3-manylinux_2_17_s390x.manylinux2014_s390x.whl (26.1 MB view details)

Uploaded Aug 21, 2026 CPython 3.10+manylinux: glibc 2.17+ s390x

ultravin-1.1.0-cp310-abi3-manylinux_2_17_ppc64le.manylinux2014_ppc64le.whl (25.8 MB view details)

Uploaded Aug 21, 2026 CPython 3.10+manylinux: glibc 2.17+ ppc64le

ultravin-1.1.0-cp310-abi3-manylinux_2_17_armv7l.manylinux2014_armv7l.whl (25.8 MB view details)

Uploaded Aug 21, 2026 CPython 3.10+manylinux: glibc 2.17+ ARMv7l

ultravin-1.1.0-cp310-abi3-manylinux_2_12_i686.manylinux2010_i686.whl (25.9 MB view details)

Uploaded Aug 21, 2026 CPython 3.10+manylinux: glibc 2.12+ i686

ultravin-1.1.0-cp310-abi3-macosx_11_0_arm64.whl (25.9 MB view details)

Uploaded Aug 21, 2026 CPython 3.10+macOS 11.0+ ARM64

ultravin-1.1.0-cp310-abi3-macosx_10_12_x86_64.whl (25.5 MB view details)

Uploaded Aug 21, 2026 CPython 3.10+macOS 10.12+ x86-64

File details

Details for the file ultravin-1.1.0.tar.gz.

File metadata

Download URL: ultravin-1.1.0.tar.gz
Upload date: Aug 21, 2026
Size: 21.2 MB
Tags: Source
Uploaded using Trusted Publishing? Yes
Uploaded via: twine/6.1.0 CPython/3.13.13

File hashes

Hashes for ultravin-1.1.0.tar.gz
Algorithm	Hash digest
SHA256	`a0ff1b22315b635a3d1173084df30f5c7649b43ce46fe72d53ab14e4262bb982`
MD5	`23253c8d48a496507fe32f7e8722dbe0`
BLAKE2b-256	`72d2331e54670862f06b9aa80a88d83d194893fc65cb9ec7291e6aba52e796ef`

Algorithm	Hash digest
SHA256	`1c19f2eaaa640dd789e2de273dda3183089b2e9a5bd6492d9843743eb3a81471`
MD5	`5e6d9c734972dd676c81c2557d41561e`
BLAKE2b-256	`eee6eac2419c6c41ecd4024442f636a8d9c646be30dd463846842887a7803c91`

Algorithm	Hash digest
SHA256	`21b4aa669ce897c2c7734ea1ca33eb73f13fefe1b9a71984b17927e7d4c51be7`
MD5	`6c34dbfc7da29f557853eace71c9dfc5`
BLAKE2b-256	`291f06b28c5402c428b05a1bbee30e6a8d4e4b8dfbec22240e6e8efedad683d7`

Algorithm	Hash digest
SHA256	`86ece0c08dd534b2fb4289b8e46ff64a4616d4c057acf2fadc01e93561c885be`
MD5	`fcba6359c76037ecf6348b1cf921b881`
BLAKE2b-256	`2c965554745da9d8980173f50008805d05ad515567ab00d8dc6896384f438872`

Algorithm	Hash digest
SHA256	`f228ab37b48b55abbb5a8ec3de86cc2af6a625146666d005645a74b3ac8c50ad`
MD5	`e80b20c75e4ad2348a948651d5fe2850`
BLAKE2b-256	`276e62a6efea86c0f27d471a5857e4afdc92513a7420f5d9f934a74b7f3660ec`

Algorithm	Hash digest
SHA256	`26db89ba19ce66f99f1d3abe1e56a2d57a70064ccf6122f83462ea82198c4874`
MD5	`7553487b3d77b589beeb05ee58b81421`
BLAKE2b-256	`b6ac26bc12aba4fad5b5b1b8673f11231d5c1f88c96db5d6a663bdcaa27e04a8`

Algorithm	Hash digest
SHA256	`077127bf2f457f7483b4b2e90f0bfb532925737df481f01a006415e5d5a90d5c`
MD5	`4c8ca2c94cf37b455d2420ce4590394b`
BLAKE2b-256	`de30db6361930134b5eb22b17b413b87b80134be6db65e1beb68275d024ef652`

Algorithm	Hash digest
SHA256	`ff2889f3b502976032c3445d9e66ddfcda0ecaea1cbabaa9d0390f0f5d0c5131`
MD5	`2abbd81546b7d6a06df453442de75192`
BLAKE2b-256	`8f1da729e36b2dd35224c96f15c373553d949990174f7cbecba68f5838a2adbe`

Algorithm	Hash digest
SHA256	`befb80ec58f01247c16c6a6a50ff38614af40a273d78b7999d3b6467e35a6f2f`
MD5	`9bfe40f1789310356ffc1c22995d4e76`
BLAKE2b-256	`17703b4dc6e057d8d4b886d777d34dea37a08e36f6ad57ba4440bbf70c76742a`

Algorithm	Hash digest
SHA256	`fbb50d2c385729669a326eb446f9e5d624eecc66c852cea7a8965467a07b4c9f`
MD5	`3f597d68ccca27ff575b5ddf352e22fb`
BLAKE2b-256	`758c3810467112a243548daacee3cd5869f7170f1049991161f62813d2758c21`

Algorithm	Hash digest
SHA256	`d9b60784ab887c9bf1964127926683a841229c9075581f2af260f073ff5888ac`
MD5	`dfc4037c8281da32ffb6dca7c72a4a51`
BLAKE2b-256	`91b0d9931583271ea3c5d4acd453d81912399aeef7138f8000dd0e34b51868c8`

Algorithm	Hash digest
SHA256	`b213a56214256681444966849655ae58de84f71648a4ac4693bbc364d78c2547`
MD5	`fdb533c707784d83486a1789bd34b27e`
BLAKE2b-256	`f5e41f4a8c38aa780c0f75f18065a53a1bed743c6141ddc5bdd8c91cea3ccdb8`

Algorithm	Hash digest
SHA256	`846061ef44abfe80a4af17cb3c77e9da4f932cfac6c586d8a497a74293816519`
MD5	`4f2367410599dd02e3e1fc305e07d00c`
BLAKE2b-256	`5c9ba014f1519b2917b5b0d84e0c3ccafb0622e022272cd11a8739d2412592f9`

Algorithm	Hash digest
SHA256	`80cef68acf58c5c235c228ca60cb9dc75aef4d2fb968ea604097d50e1c068b82`
MD5	`a24e869c3be487c9640285dfc38e44bc`
BLAKE2b-256	`f98df14f74682fb5aa98a72f3821511cf3bce9dfcfe1877fd7bbb9aebbcf05a4`

Algorithm	Hash digest
SHA256	`d355ab6baa4cecd03fe5914840616ce157368b46a5f653176231a6056be20793`
MD5	`bacc3baae9bdd38d718a3aa7ca647c91`
BLAKE2b-256	`f915f0e615b8142cadc7afb153c3dc8c1d4d604f670232128ed9cb59cee6e240`

Algorithm	Hash digest
SHA256	`75de859002a6f80ba783668bd562814ba99be55e2756bcc336eed09a1f8d96c7`
MD5	`0815384435c0a5366958fb8f4355d020`
BLAKE2b-256	`e94de2e1399a0f415160accdcfb4a13584120139678817c0003746708b4fab83`

Algorithm	Hash digest
SHA256	`79482963820a7551d219a5d7c44e9c4ed33b62a5ec85cc2829c00746f568b028`
MD5	`101aac5196ebe59647ec450b179f15d2`
BLAKE2b-256	`28d9d7813bae30bbfa8cacfe3015213c11f801f1b596dc9f38f2e887b63861da`

ultravin 1.1.0

ultravin

Getting Started

Installation

Usage

Datasets

Benchmarks

License

Project links

Key dates

1 maintainer

Credits

GitHub Statistics

License expression

Requires

Download files

Source Distribution

Built Distributions

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata