Written and maintained by CASRAI Editorial Board
Published
On this page
A GeoPackage is an open, portable file format from the Open Geospatial Consortium (OGC) for storing and transferring geospatial data: vector features, tile sets for map imagery, and non-spatial attribute tables all sit in one SQLite-based file with the extension .gpkg. Researchers use it to keep a spatial dataset, its layers and its attributes together in a single, self-describing file that can be read and updated in place, without converting it first.
What is a GeoPackage (.gpkg)?
The GeoPackage project site describes the format as an open, platform-independent, portable, self-describing and compact container for geospatial information, built on SQLite. The OGC standard page for GeoPackage states that the specification defines the schema, table definitions, integrity assertions, format limitations, content constraints and an extension mechanism. In practice that means a .gpkg file is a SQLite database whose tables follow rules written down in a public standard, so any software that implements the standard can interpret the layers inside.
The standard distinguishes what a GeoPackage can hold:
- Vector features: points, lines and polygons with their attributes.
- Tile matrix sets: pre-rendered imagery or raster map tiles at multiple zoom levels.
- Non-spatial attributes: plain tables with no geometry, such as lookup tables or survey records that join to features.
- Extensions: optional, declared additions to the base schema.
The project site also notes that a GeoPackage can be read and updated in its native storage format, with no intermediate translation step. This is the main practical difference from an exchange format that has to be exported and re-imported before each edit. It is also why the format suits a working research project and not only a final deliverable: the same file can be the analysis database and the thing you archive.
The OGC page lists 1.4.0 as the latest version, document 12-128r19, with release notes in document 23-018r1. The project site lists the versions adopted by the OGC as 1.4.0, 1.3.1, 1.3.0, 1.2.1, 1.2.0, 1.1.0 and 1.0.1. For the wider standards body behind it, see the CASRAI guide to the Open Geospatial Consortium.
How a GeoPackage is structured
Because the container is SQLite, a GeoPackage inherits SQLite’s file-level properties. The SQLite documentation on application file formats lists the advantages of a single-file database: atomic transactions, cross-platform use, and the ability to query the content with SQL. SQLite also supports a four-byte Application ID in the file header, which is how software tells a GeoPackage from any other SQLite database.
The Library of Congress format description for GeoPackage records the identifying details of the file. A GeoPackage begins with the bytes of the standard SQLite header, SQLite format 3. At byte offset 68 the application_id field holds the four ASCII characters GPKG (hexadecimal 47 50 4B 47); the 1.0 and 1.1 versions used GP10 and GP11 instead. The user_version field carries the version number, and a value of 10200 means version 1.2. The registered media type is application/geopackage+sqlite3.
Inside the file, each vector layer is one table with one geometry column. GDAL’s GeoPackage driver documentation states that each table has a single geometry column, and that a spatial index is created by default (the SPATIAL_INDEX layer creation option defaults to YES), implemented with SQLite’s R-tree structure. A practical consequence for research data is that a layer with two geometry fields, such as a polygon and a centroid for the same record, must be split into two layers or recorded as one geometry plus a derived field.
The Library of Congress also notes that the format has optional tables for metadata based on ISO 19115, the geographic information metadata standard. Using them is a choice made by whoever creates the file, not an automatic feature. See the CASRAI dictionary entry for metadata for the general concept.
GeoPackage versions and identifiers
Version matters for reproducibility, because software released before a version appeared may not read it, and because a file records its own version in the header fields described above. The data table below sets out the identifiers that the Library of Congress record documents for the first three versions and the change it attributes to each.
Two points about the version history are worth stating plainly. First, version 1.0 dates from 2014 and the Library of Congress record notes it had been deprecated by 2016, so an old .gpkg from a legacy project may carry the GP10 identifier and be worth converting to a current version. Second, version 1.2 added support for non-spatial attribute tables, which is what lets a single GeoPackage hold survey tables next to map layers. Which version GDAL writes is controlled by the VERSION creation option: AUTO writes 1.4 from GDAL 3.11 and 1.2 in earlier releases, and you can set the value explicitly when you must match a recipient’s software.
GeoPackage vs shapefile and other formats
Searchers usually ask this question because the shapefile is the long-standing default. The documented contrasts are these:
- One file, several layers. A single .gpkg can hold many vector layers, tile sets and attribute tables. GDAL’s documentation shows that converting a directory of shapefiles produces one table per input file, all inside one GeoPackage.
- Raster tiles. The GeoPackage project site compares the format with MBTiles: a GeoPackage can store multiple tile sets in one file, use other projections through an extension, and mix JPEG and PNG tiles.
- Query with SQL. Because the container is SQLite, layers can be queried with SQL. GDAL’s ogrinfo utility accepts an SQL statement against a .gpkg file.
- Preservation standing. The Library of Congress Recommended Formats Statement lists GeoPackage as a preferred format for several GIS and cartographic categories, and the SQLite documentation reports that the Library of Congress recommends SQLite itself as a storage format for long-term preservation of digital content.
Before archiving in any format, check its own specification for file-size and field-name limits that could affect your data.
How to create and use a GeoPackage
With GDAL ogr2ogr
The GDAL driver documentation gives the basic conversion of a shapefile into a GeoPackage. The output file must not already exist, or the command will not create a new one:
ogr2ogr -f GPKG filename.gpkg abc.shp
To add the contents of another GeoPackage to an existing one, the documented form uses the -append option:
ogr2ogr -append output.gpkg input.gpkg
Pointing ogr2ogr at a directory of shapefiles writes each file as its own table in one GeoPackage. GDAL also reads and writes compressed .gpkg.zip files from version 3.7.
With Python and GeoPandas
The GeoPandas input/output guide documents writing several GeoDataFrames to one file as separate layers by repeating the call with a different layer name:
countries_gdf.to_file("package.gpkg", layer="countries", driver="GPKG")cities_gdf.to_file("package.gpkg", layer="cities", driver="GPKG")
The same guide warns that columns holding Python tuples or lists cannot be saved to GeoPackage or Shapefile and must be converted to a supported type first, and that formats such as GeoPackage support only a single geometry column per layer. It also notes that GeoPackage stores a feature ID (fid) per feature that is not loaded as a column by default; with the pyogrio engine, passing fid_as_index=True makes it the index. Coordinate transformations for data you bring into a layer are covered in the guide to pyproj.
In desktop GIS
Desktop GIS programs can open a .gpkg directly because it is an open standard; the CASRAI guide to using QGIS covers the research workflow in that application.
Using GeoPackage in research data management
For a research office or a data steward, the format answers a recurring problem: a spatial dataset that arrives as a folder of loosely related files, with attribute tables, imagery and notes stored separately. A GeoPackage lets the layers, the joined tables and any embedded metadata travel as one file. The Library of Congress record also reports that national mapping agencies, among them the US Geological Survey and the UK Ordnance Survey, distribute data in the format, which helps when your inputs and outputs use the same container.
A reproducibility checklist for a dataset that includes a .gpkg, written as editorial guidance and not as a requirement of the standard:
- State the GeoPackage version, read from the user_version field or the VERSION option you used to write the file.
- Name every layer and say what each one holds, including any non-spatial tables.
- Record the coordinate reference system of each layer.
- Record the software and its version used to create the file, for example the GDAL release, since defaults such as the written version change between releases.
- Use the optional metadata tables, or an accompanying descriptive record, so the file explains itself; the guide to making a dataset FAIR sets out the wider checklist.
- Deposit the file in a repository that accepts it and describes the format; see how to choose an open data repository.
Limits and common mistakes
- No built-in security. The GeoPackage project site states that the format has no explicit security features, although some users apply the SQLite Encryption Extension. The Library of Congress record likewise says the specification contains no encryption. Do not treat a .gpkg as protected storage for sensitive location data.
- Overwriting by accident. ogr2ogr will not write into an existing output file unless you use the -append option, so scripts that rerun a conversion need to delete or version the output deliberately.
- Several geometry columns. One geometry column per table is the rule, so convert extra geometries to separate layers or to text such as WKT before saving.
- Assuming every version is readable everywhere. An older application may not open a file written as version 1.4. When a collaborator’s software is unknown, set the VERSION option explicitly and say so in the data documentation.
- Treating the file as self-documenting enough. The format is self-describing in the technical sense: software can read its tables and layers. That is not the same as a human-readable description of what the data mean and how they were collected.
Sources
- GeoPackage.org: GeoPackage, an open standard for geospatial data, checked 2026-11-17
- Open Geospatial Consortium: GeoPackage standard, checked 2026-11-17
- GDAL: GeoPackage vector driver, checked 2026-11-17
- SQLite: Appropriate uses for SQLite, SQLite as an application file format, checked 2026-11-17
- Library of Congress: GeoPackage format description (fdd000520), checked 2026-11-17
- GeoPandas: Reading and writing files, checked 2026-11-17
Data: GeoPackage versions: header identifiers and recorded changes
Compares the first three GeoPackage versions by the application_id written at byte offset 68 of the SQLite header, the user_version value, the year the Library of Congress format description records, and the change it records. Compiled from the Library of Congress GeoPackage format description (fdd000520, updated 2024-05-06) and the OGC and GeoPackage.org version lists, checked 2026-11-17.
Period covered: 2014/2017.
| GeoPackage version | application_id (ASCII) | user_version | Year recorded | Recorded change or status |
|---|---|---|---|---|
| 1.0 | GP10 | Not recorded | 2014 | Deprecated by 2016 |
| 1.1 | GP11 | Not recorded | 2016 | Revision of the 1.0 specification |
| 1.2 | GPKG | 10200 | 2017 | Added non-spatial attribute tables; registered media type application/geopackage+sqlite3 |
Sources
- Library of Congress: GeoPackage format description (accessed 2026-11-17)
- GeoPackage.org (accessed 2026-11-17)
- OGC: GeoPackage standard (accessed 2026-11-17)
Compiled by CASRAI from the sources above. Free to reuse under CC BY 4.0 with attribution.







