Skip to main content
The release publishes SQLite and Parquet files. This guide uses DuckDB’s SQLite extension; DuckDB is not an additional native database export in the release.
These instructions use v5.2.0-export.1, published 3 November 2026. Its core tables contain 250 countries, 5,327 states and 156,169 city records. API data and installed package snapshots can differ. Check the latest release before choosing another version.

Download the release

Run these POSIX-shell commands in a new directory. Downloads are compressed; extract them before opening or importing.

Install DuckDB

Use a Python version supported by the DuckDB release you install:
The first extension installation requires network access. Review the DuckDB SQLite extension documentation for deployment without network access.

Query SQLite in place

The pinned release has 156,169 city records.

Create an analytical copy

Use a new destination file. This copies rows and columns; SQLite indexes, constraints and defaults are not recreated by CREATE TABLE AS.

Query the hierarchy

Names of parent places are joined from their tables. cities does not store country_name or state_name; use a left join for nullable state links.

Troubleshooting

  • Confirm that you selected the export for your database engine; SQL dialects are not interchangeable.
  • Check the release tag and source files when counts differ. Counts from an API or a package can describe another snapshot.
  • Inspect the actual table definitions before selecting columns. See the schema reference.
Back up your database before replacing data or changing its schema. Keep release and source notices with distributed data; review the ODbL licence. DuckDB can also query a Parquet extract. A city-only file does not include the separate parent tables; retrieve matching reference files from the release source commit when you need joins. See the DuckDB documentation for Parquet, Arrow and analytical SQL.