Install & Compatibility
Where this runs
tested against v0.19.1 · 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.940 runs
build_error
glibcpy 3.10–3.940 runs
installs and imports cleanly · install 17.5s · import 2.122s · 520MB
527MB installed
● package 527MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
datashader
✓ import datashader as ds
transfer_functions
✓ import datashader.transfer_functions as tf
This quickstart demonstrates the core Datashader workflow: generating data, defining a Canvas, aggregating data points onto the canvas grid, and then shading the aggregated result into a raster image. The example uses randomly generated data and shades it based on a 'value' column. It concludes by converting the output to a PIL Image object to verify successful execution, which can then be displayed or saved.
import datashader as ds
import datashader.transfer_functions as tf
import pandas as pd
import numpy as np
from PIL import Image
# 1. Generate some example data
num_points = 100_000
data = pd.DataFrame({
'x': np.random.normal(0, 1, num_points),
'y': np.random.normal(0, 1, num_points),
'value': np.random.rand(num_points) # For coloring
})
# 2. Create a Canvas to define the aggregation grid
canvas = ds.Canvas(plot_width=400, plot_height=400)
# 3. Aggregate the data using the mean of 'value'
agg = canvas.points(data, 'x', 'y', agg=ds.mean('value'))
# 4. Shade the aggregated data into an image
img = tf.shade(agg, cmap=['lightblue', 'darkblue'], how='linear')
# To make it runnable and confirm output, convert to PIL Image object
pil_img = img.to_pil()
assert isinstance(pil_img, Image.Image)
# In a real application, you would typically save it or display it
# using a visualization library like HoloViews or Bokeh.
# pil_img.save("datashader_quickstart.png")
Debug
Known issues
breakingPython 3.9 support was officially dropped in v0.18.0. Furthermore, v0.17.0 increased the minimum supported Python version to 3.10.fixUpgrade your Python environment to 3.10 or newer before upgrading Datashader to versions 0.17.0 or later.
affects: >=0.17.0
breakingThe Datashader command-line interface (CLI) was removed in v0.19.0. Functionality previously available via the CLI must now be accessed programmatically.fixMigrate any CLI-based workflows to use the Python API. Consult the documentation for equivalent programmatic methods.
affects: >=0.19.0
gotchaSince v0.17.0, `Pillow` (for image output) and `Dask` (for large datasets) are optional dependencies. They are no longer automatically installed with `pip install datashader`.fixIf you rely on image output or Dask for large data, install these explicitly: `pip install datashader[dask,pillow]`.
affects: >=0.17.0
gotchaPrior to v0.16.0, GeoPandas GeoDataFrames often required conversion to SpatialPandas before use with Datashader. V0.16.0 introduced direct support for many GeoPandas geometry types (e.g., LineString, Polygon) in `Canvas` functions, simplifying geospatial workflows.fixIf using GeoPandas, upgrade to Datashader v0.16.0 or newer to leverage direct GeoDataFrame support and remove SpatialPandas conversion steps.
affects: <0.16.0
gotchaA bug causing a segmentation fault during `quadmesh` reduction, specifically when array sizes were exceeded, was present in versions up to 0.18.1 and fixed in v0.18.2.fixUpgrade to Datashader v0.18.2 or newer to resolve the quadmesh segmentation fault issue.
affects: >=0.18.0, <0.18.2
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'datashader'
This error most commonly occurs because the `datashader` package is not installed in the active Python environment, or there's a naming conflict where a local Python file is incorrectly named 'datashader.py'.
fixEnsure `datashader` is correctly installed using `conda install -c pyviz datashader` (recommended for performance with optimized numerical libraries) or `pip install datashader`. If you have a local script named 'datashader.py', rename it to avoid conflicts.
TypeError: Cannot cast array data from dtype('int64') to dtype('int32') according to the rule 'safe'.
This `TypeError` typically arises from compatibility issues between `datashader` (specifically its Numba/NumPy-accelerated parts) and certain Python versions (e.g., Python 3.8+) or incompatible NumPy versions.
fixTry to ensure compatibility by installing `datashader` and its dependencies (like `numba` and `numpy`) from the `pyviz` channel using `conda install -c pyviz holoviews bokeh panel datashader hvplot jupyterlab`. If the issue persists, consider temporarily downgrading your Python version to a known compatible one (e.g., Python 3.7 or 3.9) as reported in older discussions, or specifically managing `numba` and `numpy` versions.
AttributeError: 'module' object has no attribute 'shade'
This error usually indicates that the `datashader` library is an outdated version, or the `shade` function is being imported from an incorrect module. The `shade` function is part of `datashader.transfer_functions`.
fixUpgrade `datashader` to the latest version (`conda update datashader -c pyviz` or `pip install --upgrade datashader`) and ensure you are importing `shade` correctly, typically as `from datashader.transfer_functions import shade`.
ValueError: Must install dask-expr to activate query planning.
This `ValueError` (or a related `ImportError: Dask dataframe requirements are not installed.`) occurs because newer versions of `dask` (especially when used with Python 3.11+) rely on the `dask-expr` package for optimized query planning, and `datashader` might trigger this requirement if `dask-expr` is missing.
fixInstall the `dask-expr` package in your environment using either `pip install dask[dataframe]` (which includes `dask-expr`) or `conda install dask-expr`.
TypeError: Input must be an xarray.DataArray
The datashader.transfer_functions.shade function was called directly with a pandas.DataFrame or dask.DataFrame instead of an aggregated xarray.DataArray.
fixFirst aggregate the data using a datashader.Canvas method (e.g., `points`, `line`) to produce an xarray.DataArray before passing it to tf.shade.
Upgrade
Version history
0.19.1latest on PyPI · released May 19, 2026
Audit
Dependencies
numbarequiredCore dependency for high-performance data aggregation.
numpyrequiredRequired for numerical operations and array handling.
pandasrequiredCommon data input format, often used with Datashader.
xarrayrequiredCommon data input format for N-dimensional data.
scipyrequiredUsed for specific reductions and operations like edge bundling.
pillowoptionalRequired for generating image outputs from shaded aggregations.
daskoptionalEnables processing of out-of-core and distributed datasets.
cudfoptionalProvides GPU-accelerated dataframes for GPU-native processing.
geopandasoptionalEnables direct visualization of geospatial data.