polars-pycountry¶

ISO 3166 and ISO 4217 code lookup for Polars, as a native Rust expression plugin.

Turning a country column into codes looks like a dictionary lookup until you meet real data. US, USA, 840, United States, United States of America and 🇺🇸 are all the same country; Côte d'Ivoire and Cote d'Ivoire are not the same string; CA is Canada or California depending on the column next to it. The reference answer in Python is pycountry — a good library, but a Python one. Inside Polars it can only be driven through Expr.map_elements, one interpreter round-trip per row.

This package reads the same iso-codes tables pycountry ships, implements its lookup rules in Rust, and exposes them as ordinary Polars expressions. It is built to produce identical output to pycountry, not merely similar output — see Correctness.

import polars as pl
import polars_pycountry as pc

df = pl.DataFrame({
    "country": ["USA", "united kingdom", "276", "🇫🇷", "Nowhere", None],
})

df.with_columns(
    pc.alpha_2("country").alias("alpha_2"),
    pc.alpha_3("country").alias("alpha_3"),
    pc.name("country").alias("name"),
    pc.flag("country").alias("flag"),
)

┌────────────────┬─────────┬─────────┬────────────────┬──────┐
│ country        ┆ alpha_2 ┆ alpha_3 ┆ name           ┆ flag │
╞════════════════╪═════════╪═════════╪════════════════╪══════╡
│ USA            ┆ US      ┆ USA     ┆ United States  ┆ 🇺🇸   │
│ united kingdom ┆ GB      ┆ GBR     ┆ United Kingdom ┆ 🇬🇧   │
│ 276            ┆ DE      ┆ DEU     ┆ Germany        ┆ 🇩🇪   │
│ 🇫🇷             ┆ FR      ┆ FRA     ┆ France         ┆ 🇫🇷   │
│ Nowhere        ┆ null    ┆ null    ┆ null           ┆ null │
│ null           ┆ null    ┆ null    ┆ null           ┆ null │
└────────────────┴─────────┴─────────┴────────────────┴──────┘

Install¶

pip install polars-pycountry
# or
uv add polars-pycountry

Prebuilt wheels cover Linux (glibc and musl, x86_64 and aarch64), macOS (Intel and Apple Silicon), and Windows (x64 and arm64). There is one wheel per platform rather than one per Python version, because the extension is built against the stable ABI. An sdist is published too, so anything else builds from source given a Rust toolchain — see CONTRIBUTING.md.

pycountry is not a runtime dependency. The ISO tables are compiled into the extension; pycountry is installed only for the test suite, which asserts the two agree.

Compatibility¶

If a future Polars release bumps the plugin ABI, this package fails loudly at load rather than miscomputing.

Where to go next¶