pyproj

3.7.2 · active · verified Sun Mar 29

pyproj is a Python interface to PROJ, a powerful C library for cartographic projections and coordinate transformations. It enables precise coordinate reference system (CRS) operations, geodesic computations, and transformation between different spatial reference systems with high accuracy and comprehensive EPSG support. The library is actively maintained with frequent releases, currently at version 3.7.2.

Warnings

breaking Minimum Python version required for pyproj has increased significantly in recent 3.x releases. For pyproj 3.7.2, Python 3.11 or newer is required.
Fix: Upgrade your Python environment to 3.11 or newer, or use an older pyproj version compatible with your Python version. (e.g., pyproj 3.6.0 for Python 3.9+, pyproj 3.7.0 for Python 3.10+).
breaking Minimum PROJ C library version required for pyproj has increased. For pyproj 3.7.2, PROJ 9.4 or newer is required.
Fix: Ensure your system's PROJ installation meets the minimum requirement (PROJ 9.4+). If installing via pip, wheels often bundle PROJ, but if building from source or using conda, verify your PROJ version.
deprecated The `pyproj.Proj` class is considered a legacy interface. Its `init` keyword for initialization is deprecated.
Fix: Migrate to `pyproj.CRS` for defining Coordinate Reference Systems and `pyproj.Transformer` for performing transformations. For example, instead of `Proj(init='epsg:4326')`, use `CRS('EPSG:4326')` and `Transformer.from_crs()`.
gotcha pyproj 3.x wheels no longer include transformation grids by default. These grids are crucial for certain high-accuracy datum transformations (e.g., NAD27 to NAD83).
Fix: You may need to manually manage PROJ's data directory or install transformation grid packages separately. Consult the pyproj documentation on 'Transformation Grids' for guidance.
gotcha When performing transformations, the axis order (e.g., longitude/latitude vs. latitude/longitude, or easting/northing vs. northing/easting) can be a source of confusion. By default, PROJ might use different axis orders based on CRS definition.
Fix: Always use `always_xy=True` when creating a `Transformer` instance to ensure consistent (x, y) or (longitude, latitude) input and output order, which aligns with common GIS conventions.
breaking The default value for `return_back_azimuth` in `fwd_intermediate` and `inv_intermediate` methods of `pyproj.Geod` changed from `False` to `True` to match `fwd` and `inv` methods.
Fix: If your code relies on the previous default behavior, explicitly set `return_back_azimuth=False` when calling `fwd_intermediate` or `inv_intermediate`.

Install

pip install pyproj Install with pip
conda install -c conda-forge pyproj Install with conda-forge

Imports

CRS
```
from pyproj import CRS
```
Used for defining Coordinate Reference Systems.
Transformer
```
from pyproj import Transformer
```
The modern and recommended class for performing coordinate transformations.
Proj
```
from pyproj import Proj
```
While still available for backward compatibility, `pyproj.Proj` is a legacy interface. `pyproj.Transformer` is the recommended and more robust approach for transformations, especially for `CRS` to `CRS` conversions. Initializing with `init` is deprecated.
Geod
```
from pyproj import Geod
```
Used for geodesic calculations (e.g., distances, areas, forward/inverse problems on an ellipsoid).

Quickstart

This quickstart demonstrates how to perform a basic coordinate transformation from WGS84 geographic coordinates (longitude, latitude) to UTM Zone 33N projected coordinates (easting, northing) using `pyproj.CRS` to define the coordinate systems and `pyproj.Transformer` for the transformation. The `always_xy=True` parameter ensures a consistent (x, y) or (longitude, latitude) axis order.

from pyproj import CRS, Transformer

# Define source and target Coordinate Reference Systems (CRSs)
wgs84 = CRS('EPSG:4326')  # WGS84 Geographic CRS (longitude, latitude)
utm_zone_33n = CRS('EPSG:32633') # UTM Zone 33N Projected CRS (easting, northing)

# Create a transformer, ensuring consistent axis order (x, y / lon, lat)
transformer = Transformer.from_crs(wgs84, utm_zone_33n, always_xy=True)

# Define a point in WGS84 (longitude, latitude)
lon, lat = 10.0, 60.0

# Transform the point
x, y = transformer.transform(lon, lat)

print(f"Original WGS84 (lon, lat): ({lon}, {lat})")
print(f"Transformed UTM Zone 33N (easting, northing): ({x:.2f}, {y:.2f})")

# Transform multiple points
points_wgs84 = [(10.0, 60.0), (11.0, 61.0), (12.0, 62.0)]
transformed_points_utm = list(transformer.itransform(points_wgs84))

print(f"Transformed multiple points: {transformed_points_utm}")

view raw JSON →