Install & Compatibility
Where this runs
tested against v4.13.0 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.920 runs
build_error
glibcpy 3.10–3.920 runs
installs and imports cleanly · install 16.4s · import 4.979s · 503MB
502MB installed
● package 502MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
libpysal
✓ import libpysal
weights
✓ import libpysal.weights
from libpysal.weights import Queen
✗ from pysal.lib import weights
Since PySAL 2.0, functionality is split into sub-packages. Directly import from `libpysal.weights` instead of the metapackage's `pysal.lib`.
get_path
✓ from libpysal.examples import get_path
✗ import libpysal.examples; libpysal.examples.get_path(...)
Directly importing `get_path` is idiomatic for accessing example datasets.
Graph
✓ from libpysal.graph import Graph
This quickstart demonstrates loading a built-in geospatial dataset using `libpysal.examples`, then creating a Queen contiguity spatial weights matrix from a GeoDataFrame using `libpysal.weights`.
import libpysal
import geopandas as gpd
from libpysal.weights import Queen
# Load example dataset
url = libpysal.examples.get_path('columbus.shp')
gdf = gpd.read_file(url)
# Create queen contiguity weights
weights = Queen.from_dataframe(gdf)
# Print summary of weights
print(weights.summary())
Debug
Known issues
breakingIn v4.9.2, internal refactoring, particularly around `libpysal.common`, caused issues with star imports (`from libpysal.common import *`) in downstream packages, leading to broken production environments if dependencies were not updated properly. This was addressed by explicit imports in dependent packages.fixAvoid `from libpysal.common import *`. Ensure all numpy and other common imports are explicit, e.g., `import numpy as np`, rather than relying on `libpysal.common`.
affects: 4.9.2
breakingThe `Graph.build_kernel` method experienced regressions in v4.14.0 that were fixed in v4.14.1. If you implemented custom kernel building or relied on its precise behavior, verify functionality after upgrading from v4.14.0.fixUpgrade to `libpysal>=4.14.1` to resolve the regression in `Graph.build_kernel`.
affects: 4.14.0
deprecatedA new `Graph` class is being introduced, intended to eventually replace the legacy `Weights` objects in `libpysal.weights`. While `Weights` objects are still fully supported, users are encouraged to explore the `Graph` class for new developments.fixConsult the 'W and Graph Components' documentation for a migration guide and details on the new `Graph` class when building new spatial analysis workflows.
affects: 4.12.0 onwards
gotchaWhen creating spatial weights (e.g., contiguity weights), it's common to encounter a `UserWarning: The weights matrix is not fully connected`. This indicates that some spatial units in your dataset have no neighbors according to the chosen contiguity rule (e.g., islands, isolated points).fixThis is often not an error but an informative warning. You can inspect `weights.islands` to identify disconnected components. Depending on your analysis, you might need to adjust the contiguity rule (e.g., use K-Nearest Neighbors), drop isolated observations, or handle them specifically.
affects: All 4.x versions
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'geopandas'
`libpysal` often relies on `geopandas` for reading spatial data from files (e.g., shapefiles) and creating weights from GeoDataFrames, but `geopandas` is an optional dependency and not installed by default.
fixInstall `geopandas`: `pip install geopandas` or `pip install libpysal[plus]` for common optional dependencies.
KeyError: 'Some ID' (or similar error when accessing weight attributes)
This usually occurs when trying to access attributes or neighbors of a `libpysal.weights.W` object using IDs that are not present in its `id_order` attribute. This can happen if the input data's index was not properly aligned or handled during weights creation, or if IDs were remapped.
fixEnsure the IDs used to query the `W` object match the `W.id_order`. When creating weights from a DataFrame, ensure `use_index=True` if you intend to use the DataFrame's index. If IDs were remapped, use the remapped IDs or the `remap_ids` method.
ValueError: Geometry must be a Point or Polygon for weights construction.
Some weights construction methods (e.g., `Queen.from_dataframe`, `KNN.from_dataframe`) expect specific geometry types (e.g., polygons for contiguity, points for distance-based). If your GeoDataFrame contains mixed geometries or an unexpected type, this error will occur.
fixFilter your GeoDataFrame to include only the expected geometry types before constructing the weights, or use a weights constructor appropriate for your data. For example, use `gdf[gdf.geometry.geom_type == 'Polygon']` or `gdf[gdf.geometry.geom_type == 'Point']`.
Upgrade
Version history
4.14.1latest on PyPI · released Jan 9, 2026
Audit
Dependencies
numpyrequiredFundamental package for numerical computing.
scipyrequiredScientific computing library, used for spatial algorithms and sparse matrices.
pandasrequiredData manipulation and analysis, often used with GeoDataFrames.
shapelyrequiredRequired for geometric operations and object manipulation.
geopandasoptionalEssential for working with geospatial vector data (GeoDataFrames), especially when creating spatial weights from polygons or points.
networkxoptionalGraph theory library, used for graph-based operations and conversions.