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:
conda config --prepend channels conda-forgeconda config --set channel_priority strictconda create -n pyproj_env pyprojconda 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
- Import the class:
from pyproj import Transformer. - Create a transformer from source and target CRS. Use
always_xy=Trueso input and output are in the traditional GIS order (longitude, latitude; easting, northing):transformer = Transformer.from_crs("EPSG:4326", "EPSG:3857", always_xy=True). - Transform a point:
x, y = transformer.transform(lon, lat). - To inspect or define a CRS first, use
from pyproj import CRSandCRS.from_epsg(26915)orCRS.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 bytransform(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 (unlessradians=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_geographicreturns a boolean;crs.axis_infolists each axis;crs.to_epsg()returns an integer code orNonewhen 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. Passalways_xy=Trueand 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
- pyproj documentation, read 2026-11-08
- pyproj installation, read 2026-11-08
- Transformer API, read 2026-11-08
- Geod API, read 2026-11-08
- CRS API, read 2026-11-08
Related: normalising arrays with NumPy before spatial statistics.







