Getting Started With GeoPackage

Identifying a GeoPackage

A GeoPackage is an SQLite Database file with a .gpkg extension. If you are unsure whether a file is an SQLite database, you can use a binary or text editor to view the starting bytes of the file and see if they state SQLite format 3.

Opening a GeoPackage

There are a number of ways to open a GeoPackage.

The GeoPackage community tries to maintain a list of operational GeoPackage implementations and this list can be found on the implementations page. Additional information on specific products and versions of products that implement GeoPackage can also be found at You can search by specific versions of the GeoPackage standard. Note: Search for all implementing products.

Creating a GeoPackage

Similarly, if you wish to create a new GeoPackage from scratch or from an existing source file such as a ShapeFile or .csv, below are some suggestions:

Checking a GeoPackage Version

Using a direct SQL interface such as DB Browser is the easiest way to check a GeoPackage version. SQLite uses pragma statements to implement non-standard SQL functions. These statements can be executed just like any other SQL statement and where relevant, they return a result set. The two pragmas you need to know are:

What is in a GeoPackage

Like other relational databases, GeoPackages contain a number of tables. These tables fall into two categories, user-defined data tables and metadata tables. GeoPackages contain two mandatory metadata tables, gpkg_contents and gpkg_spatial_ref_sys. The presence of other metadata tables is dictated by the content being stored (see Content Types). The name of the user-defined data table is the primary key for gpkg_contents and generally is a foreign key for content-specific metadata tables.


The gpkg_contents table is the table of contents for a GeoPackage. The mandatory columns in this table are:


For content that has spatial reference (including but not limited to tiles and features), each row in contents must reference a coordinate reference system which is stored in the gpkg_spatial_ref_sys table. The mandatory columns in this table are:

At least three rows must be in this table. There must be one row for each of the following srs_id column values:

However, many more rows that reference other coordinate reference systems (CRSs) are possible. Using CRSs incorrectly is one of the most common ways to break GeoPackage interoperability. When in doubt, discuss CRSs with a geospatial expert to ensure that you are using an appropriate coordinate reference system for your situation.

Content Types


Vector feature data are geographic entities including conceptual ones such as districts, real world objects such as roads and rivers, and observations. (An observation is an act that results in the estimation of the value of a feature property, and involves application of a specified procedure, such as a sensor, instrument, algorithm or process chain. A temperature at a given geographic location provided by a sensor is an example of an observation.) For vector feature data, there is one additional required table: gpkg_geometry_columns. Features are stored in the user-defined data tables identified by the table_name values in gpkg_contents (one table per row).

Figure 1: UML Diagram of Features tables


The gpkg_geometry_columns table describes the geometry for a particular Features table. Each feature table must have a corresponding row in this table. The required columns in this table are:

User-defined Data Tables

Features are stored in user-defined data tables. Each features table has exactly one geometry column, a BLOB. (The structure of this BLOB is described here.) The OGC Simple Features geometry types are the supported geometry types. Other than the geometry column and a primary key, the schema of a features table is up to the implementer. Properties (text, integer, or real) provide additional information about each feature. The GeoPackage standard has an example schema.


The GeoPackage Tiles option specifies a mechanism for storing raster data in tile pyramids. “Tile pyramid” refers to the concept of pyramid structure of tiles of different spatial extent and resolution at different zoom levels, and the tile data itself. “Tile” refers to an individual raster image such as a PNG or JPEG that covers a specific geographic area. “Tile matrix” refers to rows and columns of tiles that all have the same spatial extent and resolution at a particular zoom level. “Tile matrix set” refers to the definition of a tile pyramid’s tiling structure. This mechanism is based on the model for tile matrix sets described in Section 6 of the WMTS Implementation Specification.

If tiles are to be included in a GeoPackage, there are two additional required metadata tables, gpkg_tile_matrix_set and gpkg_tile_matrix. In addition to these tables, each tile pyramid requires a user-defined table that contains the actual tiles.

Figure 2: UML Diagram of Tiles tables


The gpkg_tile_matrix_set table describes names a tile matrix set (pyramid). The columns in this table are:


Each tile matrix set is composed of one or more tile matrices, each identified by its zoom level. The required columns in this table are:

By default, zoom levels are separated by powers of two, but if this is inappropriate for your scenario, other multiples are possible by using the Zoom Other Levels extension.

User Data Tables

The physical tiles (data) are stored in user data tables with a specific schema. The required columns for these tables are:

Unless you use an extension, PNG and JPG are the two supported file types for the tiles. PNG is generally better for synthetic data (i.e., digital maps) because it is lossless and its compression codec compresses synthetic data fairly well. JPG is generally better for natural data (i.e., satellite or aerial imagery) due to its superior (though lossy) compression. However, since PNG supports alpha transparency and JPG does not, it is common to use PNG tiles around the boundary of a tile pyramid. This allows users to see the data underneath the tile boundaries. JPG files have an adjustable compression rating. We have found that a ratings in the range 50-75 (out of 100) work best for imagery. Ratings that are too high use too much space and ratings that are too low have too many visible artifacts. Within the 50-75 range it is a reasonable tradeoff between file size and image quality.

Tile pyramids may be sparsely populated. This is a good way to manage GeoPackage size. Applications should be aware of this possibility and if possible, drop to the next zoom level to render that part of the map.


Attributes are tables that only contain non-spatial data. This data is commonly joined with spatial data as required by an application. The rules for attribute data are pretty wide open in the GeoPackage standard.