Skip to main content
v2026.11,986 entries · CC-BY 4.0

pyproj: Python Library for Coordinate Transformations and Geodesics

pyproj install, first coordinate transformation, Geod distances, and the always_xy axis-order fix for researchers working with spatial data in Python.

Written and maintained by CASRAI Editorial Board

Published · Last updated

On this page

pyproj is the Python interface to PROJ, the cartographic projections and coordinate transformations library. Researchers use it to convert GPS or survey coordinates between coordinate reference systems (CRS), and to compute distances and azimuths on the ellipsoid. This page shows how to install it, run a first transformation, read the output, and avoid the axis-order mistake that most often corrupts spatial data.

What pyproj is used for in research

pyproj exposes four main API modules: CRS (define and inspect coordinate reference systems), Transformer (convert coordinates between two CRS), Geod (geodesic calculations on an ellipsoid) and Proj (projection objects). Typical research uses are turning field-station longitude/latitude into projected metres for spatial statistics, harmonising datasets published in different CRS before analysis, and measuring distances between sites. Tabular and vector workflows that sit on top of it are covered in the GeoPandas guide; for finding public geospatial datasets to transform, see geoportal.

Install or access

The official installation page gives two routes. With pip:

python -m pip install pyproj

With conda, using the conda-forge channel:

  1. conda config --prepend channels conda-forge
  2. conda config --set channel_priority strict
  3. conda create -n pyproj_env pyproj
  4. conda activate pyproj_env

Requirements in the current stable documentation: Python 3.11 or later and PROJ 9.4 or later. The installation page notes that pyproj 3.7 and later needs PROJ 9.2+ and 3.8 and later needs PROJ 9.4+; Linux manylinux2014 wheels need pip 19.3 or newer. To build from source, pip install pyproj --no-binary pyproj requires PROJ to be installed already. The documentation advises against using pip inside a conda environment. pyproj 3 wheels do not include transformation grids.

Step-by-step: transform coordinates between two CRS

  1. Import the class: from pyproj import Transformer.
  2. Create a transformer from source and target CRS. Use always_xy=True so input and output are in the traditional GIS order (longitude, latitude; easting, northing): transformer = Transformer.from_crs("EPSG:4326", "EPSG:3857", always_xy=True).
  3. Transform a point: x, y = transformer.transform(lon, lat).
  4. To inspect or define a CRS first, use from pyproj import CRS and CRS.from_epsg(26915) or CRS.from_user_input(26915), which returns NAD83 / UTM zone 15N.

The full signature is Transformer.from_crs(crs_from, crs_to, always_xy=False, area_of_interest=None, authority=None, accuracy=None, allow_ballpark=None, force_over=False, only_best=None).

Distance and azimuth with Geod

For distances on the ellipsoid rather than on a projected plane, create a Geod object and call inv(lons1, lats1, lons2, lats2). Geod has no default ellipsoid, so you must pass the one your data uses, for example Geod(ellps='WGS84'). The pyproj documentation’s Boston-Portland example uses ellps='clrk66', so its published numbers are Clarke 1866 values. inv returns forward azimuth, back azimuth and distance. fwd(lons, lats, az, dist) goes the other way: from a start point, an azimuth and a distance to an end point and back azimuth.

Output and how to read it

  • Transformer.transform returns values in the target CRS’s units. The documentation’s example Transformer.from_crs("EPSG:4326","EPSG:3857") followed by transform(33, 98) gives 10909310.098 and 3895303.963, in metres for that projected CRS.
  • Geod.inv returns (azi12, azi21, dist), with the distance in metres and azimuths in degrees (unless radians=True). The documentation’s Boston to Portland example prints -66.531, 75.654 and 4164192.708, that is a distance of about 4,164 km.
  • Which CRS am I in? crs.is_geographic returns a boolean; crs.axis_info lists each axis; crs.to_epsg() returns an integer code or None when no match reaches the default 70% confidence; crs.to_wkt() defaults to WKT2_2019.

Geodesic distance versus projected distance

Straight-line distance computed from coordinates in a projected CRS depends on that projection’s distortion. Geod computes on the ellipsoid and returns metres directly; a projected CRS suited to your study area (for example a UTM zone) is the choice when you need planar geometry.

Troubleshooting

  • Results look swapped or land in the wrong place. By default (always_xy=False) pyproj follows the CRS’s own axis order, and EPSG:4326 is latitude then longitude. Pass always_xy=True and supply longitude first, or keep the default and supply latitude first. Do not mix the two.
  • Small offsets compared with another tool. pyproj 3 wheels do not bundle transformation grids, so a grid-based datum shift may not be available in a pip install. Consult the PROJ documentation on grids for your region.
  • Import or version errors. Check that the installed PROJ meets the minimum for your pyproj version (see above) and avoid mixing pip into a conda environment.
  • Which version am I running? The API reference includes a Show Versions page that prints pyproj and PROJ versions for bug reports.

Free alternatives

Tool What it does When it fits
GDAL / OSR Geospatial library with its own spatial-reference and transformation bindings You already use GDAL for raster or vector I/O
GeoPandas to_crs Reprojects whole GeoDataFrames Your data is already in a GeoDataFrame
PROJ cs2cs Command-line coordinate conversion shipped with PROJ One-off conversions or shell pipelines
Cartopy Python mapping library for projecting and plotting geospatial data Your goal is maps and figures

FAQ

What is pyproj?

The Python interface to the PROJ coordinate transformation library, with CRS, Transformer, Geod and Proj modules.

How do I install pyproj?

Run python -m pip install pyproj, or create a conda environment from conda-forge with conda create -n pyproj_env pyproj.

Why are my latitude and longitude swapped?

EPSG:4326 is defined as latitude, longitude. Use always_xy=True in Transformer.from_crs to work in longitude, latitude order.

What units does Geod return?

Distances in metres; azimuths in degrees unless radians=True.

Sources

Related: normalising arrays with NumPy before spatial statistics.

Follow CASRAI

Research-administration guidance, standards updates and independent tool reviews.

Ask CASRAI · free to try

Ask about pyproj: Python Library for Coordinate Transformations and Geodesics

2 free questions a day, no account.

An AI assistant for research: funder rules, compliance, methods and publishing. It links the sources behind its answers and labels answers that come from a web search.

Answers draw on CASRAI's guides and dictionary plus the federal and funder documents we index: Federal Register, Grants.gov, Regulations.gov and UKRI.

Works on this site and inside Claude, Cursor and the AI tools you already use.

Everything CASRAI publishes — this page, the dictionary, the guides and the news — stays open to read, with no account and no card.

Referenced across the research world

University of Cambridge logoColumbia University logoCrossref logoUniversity of Edinburgh logoHarvard University logoUniversity of Oxford logoPrinceton University logoStanford School of Medicine logoUniversity College London logoORCID logoUniversity of Cambridge logoColumbia University logoCrossref logoUniversity of Edinburgh logoHarvard University logoUniversity of Oxford logoPrinceton University logoStanford School of Medicine logoUniversity College London logoORCID logo
  • University of Cambridge logo
  • Columbia University logo
  • Crossref logo
  • University of Edinburgh logo
  • Harvard University logo
  • University of Oxford logo
  • Princeton University logo
  • Stanford School of Medicine logo
  • University College London logo
  • ORCID logo

View CASRAI adoption →