PyShp

The Python Shapefile Library (PyShp) reads and writes ESRI Shapefiles in pure Python.

• Author: Joel Lawhead
• Maintainers: Karim Bahgat
• Version: 3.0.3.dev0
• Date: 10th October, 2025
• License: MIT

Contents

• Overview
• Version Changes
• The Basics
  • Reading Shapefiles
    • The Reader Class
      • Reading Shapefiles from Local Files
      • Reading Shapefiles from Zip Files
      • Reading Shapefiles from URLs
      • Reading Shapefiles from File-Like Objects
      • Reading Shapefiles Using the Context Manager
      • Reading Shapefile Meta-Data
    • Reading Geometry
    • Reading Records
    • Reading Geometry and Records Simultaneously
  • Writing Shapefiles
    • The Writer Class
      • Writing Shapefiles to Local Files
      • Writing Shapefiles to File-Like Objects
      • Writing Shapefiles Using the Context Manager
      • Setting the Shape Type
    • Adding Records
    • Adding Geometry
    • Geometry and Record Balancing
• Advanced Use
  • Common Errors and Fixes
    • Warnings and Logging
    • Shapefile Encoding Errors
  • Reading Large Shapefiles
    • Iterating through a shapefile
    • Limiting which fields to read
    • Attribute filtering
    • Spatial filtering
  • Writing large shapefiles
    • Merging multiple shapefiles
    • Editing shapefiles
  • 3D and Other Geometry Types
    • Shapefiles with measurement (M) values
    • Shapefiles with elevation (Z) values
    • 3D MultiPatch Shapefiles
• Testing
• Contributors

Overview

The Python Shapefile Library (PyShp) provides read and write support for the Esri Shapefile format. The Shapefile format is a popular Geographic Information System vector data format created by Esri. For more information about this format please read the well-written "ESRI Shapefile Technical Description - July 1998" located at http://www.esri.com/library/whitepapers/p dfs/shapefile.pdf . The Esri document describes the shp and shx file formats. However a third file format called dbf is also required. This format is documented on the web as the "XBase File Format Description" and is a simple file-based database format created in the 1960's. For more on this specification see: http://www.clicketyclick.dk/databases/xbase/format/index.html

Both the Esri and XBase file-formats are very simple in design and memory efficient which is part of the reason the shapefile format remains popular despite the numerous ways to store and exchange GIS data available today.

This document provides examples for using PyShp to read and write shapefiles. However many more examples are continually added to the blog http://GeospatialPython.com, and by searching for PyShp on https://gis.stackexchange.com.

Currently the sample census blockgroup shapefile referenced in the examples is available on the GitHub project site at https://github.com/GeospatialPython/pyshp. These examples are straight-forward and you can also easily run them against your own shapefiles with minimal modification.

Important: If you are new to GIS you should read about map projections. Please visit: https://github.com/GeospatialPython/pyshp/wiki/Map-Projections

I sincerely hope this library eliminates the mundane distraction of simply reading and writing data, and allows you to focus on the challenging and FUN part of your geospatial project.

Version Changes

3.0.3

Type checking

• Add optional dependency, "stubs", containing the package "pyshp-stubs" generated with stubgen (to avoid including py.typed, and no longer being a single file project).

Bug fix

• Prevented UnboundLocalError when reading non-single point M and Z type Shapefiles (@ekawas-vrify).

Testing.

• Test PyShp on the Python 3.14 official release (officially released this week, no longer in beta).

3.0.2

.post1

• Update version at the top of this Readme file (to make what PyPi users see consistent with the changelog and version).

.post0

• Re-release to trigger the deploy job to publish PyShp to Pypi

Bug fix

• Deleted py.typed (probably temporarily). Including the py.typed marker file with a single file package caused type checkers to type check all other libraries installed in the same directory (whether they're typed or not, enforcing type checking for all the adjacent dirs libraries, regardless of the user's intentions for the type checker) (pointed out by @dl1jbe - thanks Thomas). Discussions will be started about a longer term fix, possibly e.g. possibly refactoring to a package, and restoring py.typed.

Code quality:

• Ruff check's UP rule added (mimicks PyUpgrade) (@mwtoews).

3.0.1

Improvements

• Reader(shp=, dbf=, shx=) now support pathlib.Paths, and any pathlike object (@mwtoews).

Bug fixes

• PyShp 3 no longer modifies the global doctest module (@JamesParrott).

Code quality

• isort replaced by Ruff check's I rule (@mwtoews).
• mypy --strict used in CI (@JamesParrott).
• LICENSE.TXT re-encoded in UTF-8 (@musicinmybrain).

3.0.0

Breaking Changes:

• Python 2 and Python 3.8 support dropped.
• Field info tuple is now a namedtuple (Field) instead of a list.
• Field type codes are now FieldType 'enum' members.
• bbox, mbox and zbox attributes are all new Namedtuples.
• Writer does not mutate Shapes.
• New custom subclasses for each shape type: Null, Multipatch, Point, Polyline, Multipoint, and Polygon, plus the latter 4's M and Z variants (Reader and Writer are still compatible with their base class, Shape, as before).
• Shape sub classes are creatable from, and serializable to bytes streams, as per the shapefile spec.

Improvements:

• Speeded up writing shapefiles by up to another ~27% (on top of the recent ~39% improvement in 2.4.1).

Code quality

• Statically typed, and checked with Mypy
• Checked with Ruff.
• f-strings
• Remove Python 2 specific functions.
• Run doctests against wheels.
• Testing of wheels before publishing them
• pyproject.toml src layout
• Slow test marked.

2.4.1

Improvements:

• Speed up writing shapefiles by up to ~39%. Combined for loops of calls to f.write(pack(...)), into single calls.

Breaking Change. Support for Python 2 and Pythons <= 3.8 to be dropped.

• PyShp 2.4.1 is the latest (and likely last) version of PyShp to support Python 2.7 and Pythons <= 3.8. These CPython versions have reached end of life.
• Future development will focus on PyShp v3.0.0 onwards (currently intended to supporting Pythons >= 3.9).
• This will not break any projects, as pip and other package managers should not install PyShp 3.0.0 (after its release) in unsupported Pythons. But we no longer promise such projects will get PyShp's latest bug fixes and features.
• If this negatively impacts your project, all feedback about this decision is welcome on our the discussion page.

2.4.0

New Features:

• Reader.iterRecords now allows start and stop to be specified, to lookup smaller ranges of records.
• Equality comparisons between Records now also require the fields to be the same (and in the same order).

Development:

• Code quality tools (Ruff format) run on PyShp
• Network, non-network, or all doctests selectable via command line args
• Network tests made runnable on localhost.

2.3.1

Bug fixes:

• Fix recently introduced issue where Reader/Writer closes file-like objects provided by user (#244)

2.3.0

New Features:

• Added support for pathlib and path-like shapefile filepaths (@mwtoews).
• Allow reading individual file extensions via filepaths.

Improvements:

• Simplified setup and deployment (@mwtoews)
• Faster shape access when missing shx file
• Switch to named logger (see #240)

Bug fixes:

• More robust handling of corrupt shapefiles (fixes #235)
• Fix errors when writing to individual file-handles (fixes #237)
• Revert previous decision to enforce geojson output ring orientation (detailed explanation at https://github.com/SciTools/cartopy/issues/2012)
• Fix test issues in environments without network access (@sebastic, @musicinmybrain).

2.2.0

New Features:

• Read shapefiles dir