---
id: zipcodes
version: "3.0.0"
license: MIT
license_treatment: permissive
maintenance: active
---

# zipcodes — Query U.S. state zipcodes without SQLite.

License: permissive · Maintenance: active · Downloads: 734.3K/mo

## 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 above — 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

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

- License: MIT (permissive)
- Python support: supports_current
- Install friction: medium
- Maintenance: active
- Downloads: 734.3K/month (top 15,000 on PyPI)
- Known vulnerabilities: none known

## Tags

us zipcode lookup, zipcode validation, zipcode query library, zip code database, zipcode filter by state, zipcode coordinates, zipcode matching, geolocation, offline-data, rust-extension

[View on SkillFed](https://skillfed.io/packages/zipcodes) · [View on PyPI](https://pypi.org/project/zipcodes/)