zipcodes

What it is and what it does

Zipcodes is a Python library for querying U.S. zipcode data with the full dataset embedded in the package itself. Since version 2.0, it is implemented in Rust and compiled into a native extension, making imports nearly instant and queries significantly faster than the pure-Python 1.x version. The library provides functions to validate zipcodes, match exact codes, search by prefix, and filter by city, state, county, timezone, or coordinates. Each zipcode record includes metadata like area codes, GPS coordinates, timezone, county, and delivery status.

The package has no runtime dependencies and requires no external database or network access—all data is decompressed lazily on first query. The embedded dataset is refreshed automatically every month from three sources: unitedstateszipcodes.org, GeoNames, and USPS ZIP Locale Detail. Installation is straightforward on modern platforms via prebuilt wheels; source builds require a Rust toolchain.

Use it for:

• Validate user-submitted zipcodes in forms or APIs without making network calls.
• Look up city, state, county, and timezone information for a given zipcode.
• Filter zipcodes by location (city, state, county) or geographic bounds (coordinates).
• Find zipcodes matching a prefix pattern for autocomplete or search features.
• Embed zipcode data in offline or air-gapped applications without external dependencies.

Worth the install?

AI-flagged interpretation of the facts on this page — verify before relying

Query and validate U.S. zipcodes with embedded data—no external dependencies, no network calls, no database files required.

Yes. Zipcodes is actively maintained, has no security vulnerabilities, carries a permissive MIT license, and solves a common task (U.S. zipcode lookup) with zero runtime dependencies and fast, embedded data. The medium install friction (compiled extension) is offset by prebuilt wheels for all major platforms and Python 3.9+. Install it if you need reliable, offline zipcode queries.

Install

zipcodes on PyPI

pip install zipcodes

uv add zipcodes

poetry add zipcodes

Installing zipcodes

Before you install

Medium install friction due to compiled Rust extension, but prebuilt wheels cover Linux (x86_64, aarch64, musl), macOS, and Windows. Active maintenance with monthly data refreshes; last release 61 days ago.

License in practice

MIT license permits commercial and private use with minimal restrictions.

Quickstart

pip install zipcodes

import zipcodes

# Validate a zipcode
if zipcodes.is_real('77429'):
    result = zipcodes.matching('77429')[0]
    print(result['city'], result['state'])

# Filter by location
zips = zipcodes.filter_by(city='Cypress', state='TX')

Requires Python 3.9+. Installing from source requires a Rust toolchain.

Verify before relying

• Whether the monthly data refresh cycle is reliable in practice and whether stale data poses a risk for time-sensitive applications.
• Performance characteristics for large-scale filtering operations (e.g., filter_by across all 40,000+ zipcodes).

Package facts

Evidence: zipcodes-3.0.0-cp39-abi3-macosx_10_12_x86_64.macosx_11_0_arm64.macosx_10_12_universal2.whl; zipcodes-3.0.0-cp39-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl; zipcodes-3.0.0-cp39-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl; zipcodes-3.0.0-cp39-abi3-musllinux_1_2_x86_64.whl; zipcodes-3.0.0-cp39-abi3-win_amd64.whl

Keywords: zipcode, zip, code, us, state, query, filter, validate, sqlite

Tags

More Utilities packages