zipcodes

library2.0.1pypypi✓ verified 84d ago

Zipcodes is a lightweight Python library for querying U.S. zip codes without needing a SQLite database. It includes a comprehensive, bundled dataset for location data, demographics, and geographic coordinates. The library is currently at version 1.3.0 and is actively maintained, with regular updates to its internal dataset to ensure accuracy and freshness.

data

pip install zipcodes

github ↗package ↗

INSTALL

IMPORT

SIG · ZIPCODES

zipcodes

datapythonv2.0.1

Install

1.6s avg

Import

624ms

Disk

17MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v2.0.1 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

py 3.10–3.920 runs

installs and imports cleanly · install 0.0s · import 0.664s · 19.7MB

glibc

py 3.10–3.920 runs

installs and imports cleanly · install 1.6s · import 0.583s · 20MB

17MB installed

● package 17MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

zipcodes

✓ import zipcodes

Demonstrates basic usage including checking if a zipcode is real, getting exact matches, filtering by city/state, and finding similar zipcodes.

import zipcodes from pprint import pprint # Check if a zipcode is real assert zipcodes.is_real('77429') print(f"Is 77429 a real zipcode? {zipcodes.is_real('77429')}") # Get exact matches for a zipcode exact_zip = zipcodes.matching('77429')[0] print("\nExact match for 77429:") pprint(exact_zip) # Filter by city and state filtered_zips = zipcodes.filter_by(city="Cypress", state="TX") print(f"\nNumber of zipcodes in Cypress, TX: {len(filtered_zips)}") # Find similar zipcodes (e.g., by prefix) similar_zips = zipcodes.similar_to('7742') print(f"\nNumber of zipcodes similar to '7742': {len(similar_zips)}")

Debug

Known issues

gotchaThis library bundles its U.S. zipcode data directly within the package. While this avoids external database dependencies (like SQLite), users should be aware that data freshness depends on new package releases. The latest dataset update was February 16, 2025 (v1.3.0).

fix

Ensure you are using the latest version of the `zipcodes` library to benefit from the most recent dataset updates. Update with `pip install --upgrade zipcodes`.

affects: <1.3.0

gotchaThe `zipcodes` library is distinct from other similarly named Python packages like `uszipcode` or `pyzipcode`. This library explicitly states it does not require the `sqlite3` module, unlike some alternatives. Ensure you are importing and using the correct library for your needs.

fix

Verify your `import` statements and package documentation to confirm you are interacting with the `zipcodes` library (from `github.com/seanpianka/zipcodes`) if that is your intention.

affects: All versions

gotchaThe library is designed for U.S. zip codes only. It does not provide functionality for international postal codes. Attempting to query non-U.S. zip codes will likely result in no matches or errors.

fix

For international postal code lookups, consider libraries or APIs specifically designed for global geocoding or country-specific postal data.

affects: All versions

Errors

Common errors & fixes

ModuleNotFoundError: No module named 'zipcodes'

The 'zipcodes' package is not installed in the current Python environment.

fix

pip install zipcodes

AttributeError: module 'zipcodes' has no attribute 'get'

The 'zipcodes' module does not have a function named 'get'; the correct function for retrieving a specific zip code is 'lookup()'.

fix

zip_code_data = zipcodes.lookup('90210')

TypeError: filter() got an unexpected keyword argument 'invalid_arg'

The 'zipcodes.filter()' function received a keyword argument that does not correspond to a valid zip code attribute.

fix

matching_zips = zipcodes.filter(state='CA', city='Los Angeles')

AttributeError: 'NoneType' object has no attribute 'city'

The 'zipcodes.lookup()' function returned 'None' because no matching zip code was found, and an attempt was made to access an attribute on this 'None' object.

fix

zip_data = zipcodes.lookup('99999')
if zip_data:
    print(zip_data.city)
else:
    print("Zip code not found.")

Upgrade

Version history

2.0.1latest on PyPI · released Jun 12, 2026

Audit

Dependencies

No dependency data recorded yet.

Agent activity

41 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/seanpianka/zipcodes ↗

packagehttps://pypi.org/project/zipcodes/ ↗