maxminddb-polars

Fast Polars expressions for MaxMind DB lookups, implemented in Rust.

The Python API follows Semantic Versioning beginning with 0.1.0. The similarly named crates.io package is the native implementation used to build the Python plugin; it does not currently expose a supported Rust API.

The package provides nested whole-record lookups for recognized MaxMind DB schemas and selective path lookups for efficient enrichment. Callers supply their own licensed or GeoLite database; no database is bundled or downloaded.

Install it from PyPI with:

python -m pip install maxminddb-polars

from pathlib import Path

import polars as pl
import maxminddb_polars as mmp

database = Path("/data/GeoLite2-City.mmdb")
frame = pl.DataFrame({"ip": ["81.2.69.142", None]})

result = frame.select(
    country=mmp.lookup_path("ip", database, ("country", "iso_code")),
    city=mmp.lookup("ip", database),
)

# The expression namespace is equivalent:
country = pl.col("ip").mmdb.lookup_path(database, ("country", "iso_code"))

Whole records infer one of the nine standard schemas from database metadata: City, Country, Enterprise, ISP, Connection Type, Anonymous IP, Density/Income, Domain, or ASN. Their stable Polars dtypes are exported from maxminddb_polars.schemas.

Pass a nested mapping or pl.Struct as dtype for a partial known record or a custom database. See Custom and partial schemas.

Inputs must have String dtype. Null inputs, lookup misses, and missing paths produce null. Invalid IP strings raise by default; pass strict=False to turn them into nulls. The package owns a strong byte snapshot for each database file generation, so atomically replace database files and construct new expressions to refresh them.

Development

Initialize the fixtures and run the checks with:

git submodule update --init --recursive
uv sync --all-extras --locked
uv run maturin develop
uv run pytest
cargo test --locked

See CONTRIBUTING.md for the complete development workflow.

Documentation:

Project policies

Project links

Data verified by PyPI on Aug 24, 2026
Data provided by the project maintainers, verified at the time the release was uploaded to PyPI.

Key dates

PyPI data
Data sourced directly from PyPI's database.
  • Released:
Newer release available (0.1.3)

1 maintainer

PyPI data
Data sourced directly from PyPI's database.
Avatar for oschwald from gravatar.com oschwald

Credits

Author: Gregory Oschwald

GitHub Statistics

Data verified by PyPI on Aug 24, 2026
The GitHub source repository was provided by the project maintainers and verified by PyPI at the time of upload. Stars, forks, and open issues/PRs are derived from that repository and have not been independently verified.

License expression

ISC
View SPDX License List

Requires

Python >=3.10

Provides Extra

test

Tags

maxmind geoip mmdb polars

Classifiers

Report project as malware

Download files

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

Source Distribution

maxminddb_polars-0.1.0.tar.gz (154.4 kB view details)

Uploaded Source

Built Distributions

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

maxminddb_polars-0.1.0-cp310-abi3-win_amd64.whl (6.6 MB view details)

Uploaded CPython 3.10+Windows x86-64

maxminddb_polars-0.1.0-cp310-abi3-musllinux_1_2_x86_64.whl (7.1 MB view details)

Uploaded CPython 3.10+musllinux: musl 1.2+ x86-64

maxminddb_polars-0.1.0-cp310-abi3-musllinux_1_2_aarch64.whl (6.7 MB view details)

Uploaded CPython 3.10+musllinux: musl 1.2+ ARM64

maxminddb_polars-0.1.0-cp310-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (7.2 MB view details)

Uploaded CPython 3.10+manylinux: glibc 2.17+ x86-64

maxminddb_polars-0.1.0-cp310-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl (6.5 MB view details)

Uploaded CPython 3.10+manylinux: glibc 2.17+ ARM64

maxminddb_polars-0.1.0-cp310-abi3-macosx_11_0_arm64.whl (6.0 MB view details)

Uploaded CPython 3.10+macOS 11.0+ ARM64

maxminddb_polars-0.1.0-cp310-abi3-macosx_10_12_x86_64.whl (6.5 MB view details)

Uploaded CPython 3.10+macOS 10.12+ x86-64

File details

Details for the file maxminddb_polars-0.1.0.tar.gz.

File metadata

  • Download URL: maxminddb_polars-0.1.0.tar.gz
  • Upload date:
  • Size: 154.4 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/6.1.0 CPython/3.13.13

File hashes

Hashes for maxminddb_polars-0.1.0.tar.gz
Algorithm Hash digest
SHA256 68196815edb3c316324e974b55c53ae5127787e0fa7a0aed68a3759b85bbcdd9
MD5 84dd77917924aa2ff07113e297a1f122
BLAKE2b-256 7ee9c72b623ad3f728012f8c2d722eca16f515564c70901b57fbcb04eba63f2d

See more details on using hashes here.

Provenance

The following attestation bundles were made for maxminddb_polars-0.1.0.tar.gz:

Publisher: release.yml on oschwald/maxminddb-polars

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file maxminddb_polars-0.1.0-cp310-abi3-win_amd64.whl.

File metadata

File hashes

Hashes for maxminddb_polars-0.1.0-cp310-abi3-win_amd64.whl
Algorithm Hash digest
SHA256 7387916a522809286f92b8505e5e5d1d86a6846acf8ce8f28d7bdfb995313613
MD5 ceb4c0a43210991d7ebd36f199ffd439
BLAKE2b-256 c99643b0d9b135f4aa52c05e71814f82bd02dc796b4ed1a731dcc86c4485d1b9

See more details on using hashes here.

Provenance

The following attestation bundles were made for maxminddb_polars-0.1.0-cp310-abi3-win_amd64.whl:

Publisher: release.yml on oschwald/maxminddb-polars

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file maxminddb_polars-0.1.0-cp310-abi3-musllinux_1_2_x86_64.whl.

File metadata

File hashes

Hashes for maxminddb_polars-0.1.0-cp310-abi3-musllinux_1_2_x86_64.whl
Algorithm Hash digest
SHA256 77aa064f122bff5f79712c6d9120aaa6c3884108a9c9bfda3d71ea7b8729fd9e
MD5 9788ab4f355b7ff751fdf833947a1dc7
BLAKE2b-256 5f567e0f23de69333a6fdd086eb006a395e804ce9e1da25152e14e00eff5caa5

See more details on using hashes here.

Provenance

The following attestation bundles were made for maxminddb_polars-0.1.0-cp310-abi3-musllinux_1_2_x86_64.whl:

Publisher: release.yml on oschwald/maxminddb-polars

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file maxminddb_polars-0.1.0-cp310-abi3-musllinux_1_2_aarch64.whl.

File metadata

File hashes

Hashes for maxminddb_polars-0.1.0-cp310-abi3-musllinux_1_2_aarch64.whl
Algorithm Hash digest
SHA256 a9254d51f2fc6a852c845ff6ae38bedc029fd354a1dba7a88eee0ef7cb6857f5
MD5 6a44780a19554d1756ec2960fa1881ce
BLAKE2b-256 2714747f1b7b3e68615a116e667a60efb1185b54955a8ca5fe23dfd4cd87eef3

See more details on using hashes here.

Provenance

The following attestation bundles were made for maxminddb_polars-0.1.0-cp310-abi3-musllinux_1_2_aarch64.whl:

Publisher: release.yml on oschwald/maxminddb-polars

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file maxminddb_polars-0.1.0-cp310-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl.

File metadata

File hashes

Hashes for maxminddb_polars-0.1.0-cp310-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm Hash digest
SHA256 c8bc235cd981174f934feb98fa26e20b2ec68d608f06aff3b53fe64835e8ae6a
MD5 79e046b78838bfcd77c8d8f612dbfb38
BLAKE2b-256 ce6d915f59fc2b81184ac965867596cc39db1ad88e77f556b715c8785a4a70fa

See more details on using hashes here.

Provenance

The following attestation bundles were made for maxminddb_polars-0.1.0-cp310-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl:

Publisher: release.yml on oschwald/maxminddb-polars

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file maxminddb_polars-0.1.0-cp310-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl.

File metadata

File hashes

Hashes for maxminddb_polars-0.1.0-cp310-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
Algorithm Hash digest
SHA256 ac4f9b87c29d55feda1960d74be73d88d74f18a85952cf7e5683a70482c85991
MD5 2007e2ccd5afaf9d070632d83606a9d2
BLAKE2b-256 0af25cca6ac4702c4bf72763f89c50a77803b59a6965fa98e9985d018af3c704

See more details on using hashes here.

Provenance

The following attestation bundles were made for maxminddb_polars-0.1.0-cp310-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl:

Publisher: release.yml on oschwald/maxminddb-polars

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file maxminddb_polars-0.1.0-cp310-abi3-macosx_11_0_arm64.whl.

File metadata

File hashes

Hashes for maxminddb_polars-0.1.0-cp310-abi3-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 f6b588068e92d18fc297070addfc62e3a810403d06c6da0d481e83f6001e9752
MD5 ba63510d74eb37ae931478cc2729b64b
BLAKE2b-256 a22d624b6442c11a007a74ddaece6655b854234dd4c4f7e8fce273b87cd04f9c

See more details on using hashes here.

Provenance

The following attestation bundles were made for maxminddb_polars-0.1.0-cp310-abi3-macosx_11_0_arm64.whl:

Publisher: release.yml on oschwald/maxminddb-polars

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file maxminddb_polars-0.1.0-cp310-abi3-macosx_10_12_x86_64.whl.

File metadata

File hashes

Hashes for maxminddb_polars-0.1.0-cp310-abi3-macosx_10_12_x86_64.whl
Algorithm Hash digest
SHA256 f5818e18afebea95ab666dec17ba2e445dfad29757d2a69d433160576cca6303
MD5 2cd40e3823076fa26a7b9c9e4cbd4489
BLAKE2b-256 790ee8c65bb57c19aa1477effa0afa0957e92ba6f536458cd31cdd0c3d1b98ba

See more details on using hashes here.

Provenance

The following attestation bundles were made for maxminddb_polars-0.1.0-cp310-abi3-macosx_10_12_x86_64.whl:

Publisher: release.yml on oschwald/maxminddb-polars

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Release history Release notifications | RSS feed

0.1.3

8 files

0.1.2

8 files

0.1.1

8 files

This release

0.1.0 This release

8 files

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Depot Continuous Integration Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page