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 14 standard schemas from database metadata: City, Country, Enterprise, ISP, Connection Type, Anonymous IP, Anonymous Plus, Residential Proxy, IP Risk, Static IP Score, User Count, 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 caches generation-safe byte snapshots up to a documented process limit, 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 26, 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:
Latest release

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 26, 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.3.tar.gz (174.3 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.3-cp310-abi3-win_amd64.whl (6.6 MB view details)

Uploaded CPython 3.10+Windows x86-64

maxminddb_polars-0.1.3-cp310-abi3-musllinux_1_2_x86_64.whl (7.3 MB view details)

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

maxminddb_polars-0.1.3-cp310-abi3-musllinux_1_2_aarch64.whl (6.9 MB view details)

Uploaded CPython 3.10+musllinux: musl 1.2+ ARM64

maxminddb_polars-0.1.3-cp310-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (7.3 MB view details)

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

maxminddb_polars-0.1.3-cp310-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl (6.7 MB view details)

Uploaded CPython 3.10+manylinux: glibc 2.17+ ARM64

maxminddb_polars-0.1.3-cp310-abi3-macosx_11_0_arm64.whl (6.1 MB view details)

Uploaded CPython 3.10+macOS 11.0+ ARM64

maxminddb_polars-0.1.3-cp310-abi3-macosx_10_12_x86_64.whl (6.6 MB view details)

Uploaded CPython 3.10+macOS 10.12+ x86-64

File details

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

File metadata

  • Download URL: maxminddb_polars-0.1.3.tar.gz
  • Upload date:
  • Size: 174.3 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for maxminddb_polars-0.1.3.tar.gz
Algorithm Hash digest
SHA256 55e6a09a4aefe7ea1f87cc92c5ffaa094e7adec5458fd8c70e4af1f0079f3d26
MD5 e5e28abfabd3dec874fd3cfd6ca4bd4a
BLAKE2b-256 f8dc39f8f52f81bac1d2c771a001ae23c87e2a2dc1e06bfb64b0e9d75795aa3f

See more details on using hashes here.

Provenance

The following attestation bundles were made for maxminddb_polars-0.1.3.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.3-cp310-abi3-win_amd64.whl.

File metadata

File hashes

Hashes for maxminddb_polars-0.1.3-cp310-abi3-win_amd64.whl
Algorithm Hash digest
SHA256 dd93b4170b9af9807bb220eecc8c5ace48a10b2948a1e1c70ddf1e4297d76659
MD5 dd4e9979b00f12320a80bbb45aa0cd62
BLAKE2b-256 2879a28a0b9a3e29ad06dbcf0f03cdba45fadad2d3ea5fb276e53f96a88fa73d

See more details on using hashes here.

Provenance

The following attestation bundles were made for maxminddb_polars-0.1.3-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.3-cp310-abi3-musllinux_1_2_x86_64.whl.

File metadata

File hashes

Hashes for maxminddb_polars-0.1.3-cp310-abi3-musllinux_1_2_x86_64.whl
Algorithm Hash digest
SHA256 4d74dd86185339e09f956d4a03fae484bd3c01c63d25e4113557b09817824c6f
MD5 9b9af7f05df165ad4b8c2c0363730564
BLAKE2b-256 05dcbdf73b6d3ac7fb3eba4cb67670f4a37fbd2fc86e397d8970f5949eac712f

See more details on using hashes here.

Provenance

The following attestation bundles were made for maxminddb_polars-0.1.3-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.3-cp310-abi3-musllinux_1_2_aarch64.whl.

File metadata

File hashes

Hashes for maxminddb_polars-0.1.3-cp310-abi3-musllinux_1_2_aarch64.whl
Algorithm Hash digest
SHA256 cb20dbdb9b1d2708f131080719cc50bed085215b11851e538d9ec351c151cff2
MD5 a25ca5cdc98b2bc92f367ce866588f72
BLAKE2b-256 12b2076a60682832f44897e986d7cfc8ef189612fa073ccdb38c1d0d63bd6919

See more details on using hashes here.

Provenance

The following attestation bundles were made for maxminddb_polars-0.1.3-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.3-cp310-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl.

File metadata

File hashes

Hashes for maxminddb_polars-0.1.3-cp310-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm Hash digest
SHA256 882a7c1b115b62a3fa168b7d1ea661603021edecf415e7b30bdba642be276ba8
MD5 04a7b3a3ff4f74c178fb2069a4134a0c
BLAKE2b-256 758cca76227027a30de4d7ee755096a2e8e2e34403795e0924769d9ce2817a65

See more details on using hashes here.

Provenance

The following attestation bundles were made for maxminddb_polars-0.1.3-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.3-cp310-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl.

File metadata

File hashes

Hashes for maxminddb_polars-0.1.3-cp310-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
Algorithm Hash digest
SHA256 57112ea0a063712c7fb60577173406bdfc1e5f73849d600a62f1185f9727d3cc
MD5 340cb28dd69b585248f94ebbeea3d298
BLAKE2b-256 c0316c3c1b1c3256c04817d073a3876a0fd2c549bea78d7932b7fbf341bccc82

See more details on using hashes here.

Provenance

The following attestation bundles were made for maxminddb_polars-0.1.3-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.3-cp310-abi3-macosx_11_0_arm64.whl.

File metadata

File hashes

Hashes for maxminddb_polars-0.1.3-cp310-abi3-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 2d58c61dbeb93d9647749543b5dac1efaee1277281e2a11901d6cfd4751ee530
MD5 013690073523eff016be51c91d7cd0c6
BLAKE2b-256 a66d812eb921fee7be011772913f6baf01a9661d4f4e12311f6e4b99d5a509af

See more details on using hashes here.

Provenance

The following attestation bundles were made for maxminddb_polars-0.1.3-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.3-cp310-abi3-macosx_10_12_x86_64.whl.

File metadata

File hashes

Hashes for maxminddb_polars-0.1.3-cp310-abi3-macosx_10_12_x86_64.whl
Algorithm Hash digest
SHA256 b74553e2de45a027ce87c3eab988fc85967f77866f4210ce42b4b9458306c6e2
MD5 c74cba6a4cfd8c08fcc71ed82af2b55a
BLAKE2b-256 0e280281eee8b7960f90dd152f5a916226a7e73ba3339ade43a8855b78f65bb3

See more details on using hashes here.

Provenance

The following attestation bundles were made for maxminddb_polars-0.1.3-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

This release

0.1.3 This release

8 files

0.1.2

8 files

0.1.1

8 files

0.1.0

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