Install & Compatibility
Where this runs
tested against v1.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
muslpy 3.10–3.95 runs
installs and imports cleanly · install 0.0s · import 0.000s · 57.3MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 5.5s · import 0.000s · 55MB
53MB installed
● package 53MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
SearchEngine
✓ from uszipcode import SearchEngine
ZipcodeSearchEngine
✓ from uszipcode import SearchEngine
✗ from uszipcode import ZipcodeSearchEngine
This class was used in older versions (e.g., 0.x) but has been renamed to `SearchEngine` in current versions (1.x).
Initialize the `SearchEngine` to interact with the US zip code database. The database will be downloaded automatically upon first use. You can then use methods like `by_zipcode` or `by_city_and_state` to retrieve detailed information.
from uszipcode import SearchEngine
# Initialize the search engine (downloads database on first run)
search = SearchEngine()
# Search by a specific zip code
zipcode = search.by_zipcode("10001")
if zipcode:
print(f"Zip Code: {zipcode.zipcode}")
print(f"City: {zipcode.major_city}")
print(f"State: {zipcode.state}")
print(f"Population: {zipcode.population}")
print(f"Latitude: {zipcode.lat}, Longitude: {zipcode.lng}")
else:
print("Zip code not found.")
# Example: Search by city and state
zipcodes_in_city = search.by_city_and_state(city="New York", state="NY")
print(f"\nFound {len(zipcodes_in_city)} zip codes in New York, NY.")
if zipcodes_in_city:
print(f"First zip code: {zipcodes_in_city[0].zipcode}")
Debug
Known issues
breakingVersion 1.0.1 and later explicitly drops support for Python 2.7. The library now requires Python 3.6 or later.fixEnsure your project runs on Python 3.6+ and upgrade your Python environment if necessary.
affects: >=1.0.1
breakingA recent update to the `sqlalchemy-mate` dependency (version 2.0.0.1) caused a breaking change, moving the `ExtendedBase` attribute. This can lead to `ModuleNotFoundError` when importing `uszipcode`.fixAs a workaround, pin `sqlalchemy-mate` to an earlier compatible version, specifically `sqlalchemy-mate==2.0.0.0` or older, in your `requirements.txt` or `pip install` command.
affects: 1.0.1 (when used with sqlalchemy-mate>=2.0.0.1)
gotchaBy default, `SearchEngine()` uses the `SimpleZipcode` database (approx. 10MB) which contains basic information. For more comprehensive data points (e.g., population density, income, education), you must explicitly request the `ComprehensiveZipcode` database (approx. 450MB).fixInitialize `SearchEngine` with `simple_or_comprehensive=SearchEngine.SimpleOrComprehensiveArgEnum.comprehensive` to access the richer dataset. Be aware of the larger download size.
affects: All 1.x versions
gotchaThe data provided, while including 2020 census data for some demographic statistics over time, still relies on Census 2010 for general population and income data. The author explicitly states a disclaimer regarding data accuracy.fixUsers should be aware of potential data freshness limitations and verify critical data points with official sources for applications requiring the latest accuracy.
affects: All 1.x versions
gotcha`ModuleNotFoundError` for `uszipcode` despite successful installation is commonly caused by multiple Python installations or conflicting virtual environments, leading to `pip` installing in one environment while the script runs in another.fixEnsure you are using the `pip` executable associated with the Python interpreter running your script (e.g., `python -m pip install uszipcode`) or activate the correct virtual environment.
affects: All versions
Upgrade
Version history
1.0.1latest on PyPI · released Jan 6, 2022
Audit
Dependencies
sqlalchemyrequiredUsed as the underlying ORM for database interactions.
sqlalchemy-materequiredA dependency that has introduced breaking changes in its 2.0.0.1 release, affecting uszipcode import.