Skip to content
Get packs

Guide · Open source

How to use deck.gl: install, layers and views explained

Updated · written with AI from the project's own documentation and checked against our catalogue data

deck.gl is an open-source visualization framework that draws large data sets in the browser using WebGL2 and WebGPU. This guide explains how it works in terms of data, layers and views, how to install it with npm or pip, and where it fits compared with other mapping and charting tools. By the end you will know the basic model you need before writing any code.

deck.glvisgl/deck.gl · ★ 14.7k · MIT

Quick start

  1. 1Check prerequisites. Make sure Node.js is available for the npm package, or Python for pydeck.
  2. 2Install the package. Run npm install deck.gl in a JavaScript project, or pip install pydeck for Python.
  3. 3Pick a starting example. Open the pure JS or React get-started guide and run one of the linked full examples.
  4. 4Supply your data. Replace the sample data with an array of objects, usually JSON.
  5. 5Add layers. Choose layers such as icons, polygons or text and configure them through their APIs.
  6. 6Choose a view. Select a map, first-person or orthographic view to display the layers.
  7. 7Iterate with the docs. Use the API documentation and playground to refine the result.

What deck.gl does and how it is organised

deck.gl maps data, usually an array of JSON objects, into a stack of visual layers such as icons, polygons or text. You then look at those layers through views, for example a map, a first-person view or an orthographic view.

The framework also handles rendering and updating of large data sets, interactive events such as picking, highlighting and filtering, and cartographic projections with integration for major basemap providers.

  • Data: an array of objects, usually JSON
  • Layers: visual building blocks such as icons, polygons and text
  • Views: how you look at the layers, such as map, first-person or orthographic

Install deck.gl with npm or pip

For JavaScript projects, install the npm module. The npm package requires Node.js. The README also lists a script tag option for quick use in a page, and separate get-started guides for plain JavaScript and React.

For Python, install the pydeck package, which lets you produce deck.gl maps from Python. pydeck requires Python.

  • Pure JS and React: use the npm module and follow the matching get-started guide
  • Script tag: load the library from a script element, as shown in the README
  • Python: use pydeck, documented on the deck.gl Read the Docs site
npm install deck.gl pip install pydeck

Create your first visualization

Start from one of the official examples rather than a blank file. The README links full examples for the script tag, pure JavaScript and React setups, so you can copy a working project and change the data.

Pass your array of data objects to a layer, add the layer to a view, and render. Adjust the layer's properties to control each aspect of how it looks.

  • Open the pure JS or React get-started guide
  • Run one of the linked full examples
  • Replace the sample data with your own array of objects

Choose layers and views for your data

Layers are the core unit of deck.gl. The README names icons, polygons and text as examples, and states that all layers offer flexible APIs for programmatic control of rendering. Composing existing layers is the fastest route to a result.

Browse the API documentation and website demos to see the layer catalog and how each layer is used. Views determine the perspective, such as map, first-person or orthographic.

  • Use the API documentation to look up each layer's options
  • Use the website demos with source links to compare layers in practice
  • Use the interactive playground to test changes without a full project

Extend deck.gl for custom rendering

If the built-in layers do not fit, deck.gl is designed to be extended. The README says core classes can be extended by users for custom use cases.

Extending classes requires more code than composing layers, so treat it as a second step after you have a working visualization.

  • Compose existing layers first
  • Extend core classes only when your rendering needs go beyond them

Check the browser and learn from the community

Rendering depends on WebGL2 support, so visualizations will not run in browsers without it. The README also lists Codepen and Observable demos, and a Slack workspace linked from the project page for questions.

The project is part of vis.gl, an OpenJS Foundation project, and contribution guidelines are in the repository.

  • Confirm your target browsers support WebGL2
  • Explore the Codepen and Observable demos for ideas
  • Ask questions in the deck.gl Slack workspace

What people use it for

  • Interactive maps over large sets of geographic points or shapes
  • Geospatial dashboards that filter and highlight large data sets
  • Producing deck.gl maps from Python with pydeck
  • Custom visualizations built by extending deck.gl core classes

Frequently asked questions

Is deck.gl free to use?

deck.gl is released under the MIT licence, as stated in this directory's listing. Check the licence file in the repository for the full terms before you use it in a commercial product.

How do I install deck.gl?

For JavaScript projects, run npm install deck.gl. For Python, run pip install pydeck. The npm package needs Node.js and pydeck needs Python.

What are the requirements for deck.gl?

You need Node.js for the npm package and Python for pydeck. Visualizations also depend on browser support for WebGL2, so older browsers without it will not render them.

Do I need to code to use deck.gl?

Yes, deck.gl is a framework for building visualizations, not a finished tool. Users without coding experience will need a ready-made application built on top of it.

What is pydeck?

pydeck is the Python wrapper for deck.gl. Install it with pip install pydeck to produce deck.gl maps from Python.

How does deck.gl compare with Leaflet or MapLibre GL JS?

Leaflet, MapLibre GL JS, Kepler.gl and Apache ECharts are comparable projects in this directory. deck.gl is aimed at GPU rendering of large data sets, while simple static charts with small data may be easier with a lighter library.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

deck.gl suits developers who need interactive maps or geospatial dashboards over tens of thousands of points or shapes, and Python users who want pydeck. It is a framework rather than a finished tool, so people who want no coding, simple charts with small data, or browsers without WebGL2 should pick a different option.

Install options & downloads