# planetlabs/notebooks: Jupyter guides for working with Planet satellite imagery

> This repository collects the Jupyter notebooks written by Planet's developers and data scientists to teach the Planet APIs, with the API key handling, Docker environment and authentication differences documented end to end.

**planetlabs/notebooks** — interactive notebooks from Planet Engineering

- Repository: https://github.com/planetlabs/notebooks
- Website: https://developers.planet.com/
- Stars: 681 · Forks: 332
- Language: Jupyter Notebook
- License: Apache-2.0
- Published: 2026-10-21 · Updated: 2026-10-21 · Language: en
- Canonical page: https://hysenlabs.com/projects/planetlabs-notebooks

## Guides, not a library, for the Planet data APIs

The planetlabs/notebooks repository is a collection of Jupyter notebooks written by the software developers, data scientists, and developer advocates at Planet. The project description calls them interactive notebooks from Planet Engineering, and the README frames them as guides designed to help you work with the APIs and tools, explore Planet data, and learn how to extract information from a large archive of high-cadence satellite imagery. The audience is a Python user who has just signed up for Planet and wants to see actual API calls rather than read endpoint documentation. The repository layout is small and honest about it: a jupyter-notebooks/ directory holding the guides themselves, a planet-notebook-docker/ directory with the container build, a README, and a CONTRIBUTING file. There is no pip package, no importable module, and no code generation step. The notebook collection is indexed by a table of contents kept under jupyter-notebooks/, and the surrounding documentation lives on the Planet developer site rather than in the repository.

## Two authentication paths that do not share credentials

The most consequential thing the README explains is that the notebooks authenticate in more than one way, and that those ways do not work together. Some notebooks authenticate with a Planet account directly, prompting a login through a web link where you confirm authorisation. Others authenticate with a Planet API key that you take from your account settings page and export as an environment variable. A third group uses the Sentinel Hub Python SDK, and here the README is explicit that this SDK uses a different authentication method from the Planet APIs and the Planet SDK for Python. The Sentinel Hub path needs a client_id and a client_secret obtained from the account manager application, and the SDK configuration is handled by the sentinelhub package itself, which reads an SHConfig object and can prompt for the credentials interactively and save them to a config location on disk. So a notebook written against Sentinel Hub will not pick up the Planet key you exported, and that is by design rather than a bug.

## Cloning the repository and exporting the API key

Getting the guides is a plain git clone, and the README splits the first run from later runs deliberately. If you have never cloned the repository, clone it and move into the directory. If you have been here before, the update path is a pull from inside the same directory, which is how you pick up guide changes.

```bash
git clone https://github.com/planetlabs/notebooks.git
cd notebooks
```

```bash
cd notebooks
git pull
```

The key itself is exported as an environment variable, and the README explains how to make it permanent by putting the same export into your shell profile.

```bash
export PL_API_KEY="YOUR-API-KEY"
```

Inside the notebooks the environment variable is read into a Python name, and the example is written out with comments so you can see what each line does. The variable name in Python is deliberately different from the environment variable name, so a notebook that reads PLANET_API_KEY will fail with a confusing None if the export was never done.

```python
# Import the os module in order to access environment variables
import os

# Set up the API Key from the `PL_API_KEY` environment variable
PLANET_API_KEY = os.getenv('PL_API_KEY')
```

## The Docker image exists because the dependency stack is awkward

The README gives the reason for the container plainly: the notebooks rely on a complex stack of technologies that are not always easy to install and properly configure. The image is built from the planet-notebook-docker/ directory that sits in the repository, and the build is the slow part, taking somewhere between ten minutes and an hour depending on network speed and how long Anaconda takes to configure its environment. That is a fair warning to read before starting, since a first build is not a quick operation.

```bash
docker build -t planet-notebooks planet-notebook-docker/
```

The image is tagged planet-notebooks, and the documentation notes that you may need to rebuild it if the repository changes or if you want newer versions of the Planet SDK for Python. That rebuild note is a practical consequence of baking dependencies into an image, and it is the main operational cost of this route.

## Running the container and reaching Jupyter on port 8888

The run command is a single line, executed from the cloned repository root in Unix bash, Windows PowerShell, Git Bash, or WSL, and it threads the API key in as an environment variable at launch time rather than baking it into the image. The volume mount maps your local jupyter-notebooks directory into the container so your work persists on the host side.

```bash
docker run -it --rm -p 8888:8888 -v "$(pwd)/jupyter-notebooks:/home/jovyan/work" -e PL_API_KEY='your-key' planet-notebooks
```

Five things are happening in that command. Port 8888 is published so the container is reachable on localhost. The jupyter-notebooks folder is mounted at /home/jovyan/work. The key is passed in as PL_API_KEY. You land in an interactive terminal that is also served to the browser. And the container removes itself on exit because of the --rm flag, so restarting means rerunning the command. The README adds that permission errors are resolved by adding sudo on Linux and Mac, or by running PowerShell as Administrator on Windows. The CLI prints the address to open, and the token in it changes on every start, which means bookmarking a URL from an earlier session will not work.

## Licensing, releases, and what the repository does not contain

Two administrative details are worth knowing before you build on these guides. The project is published under Apache-2.0, while the README describes the guides themselves as released under APLv2, so if you are redistributing a notebook or mixing its text into your own documentation, the licence terms differ between the repository and the guide content. On the release side there are no GitHub releases at all, which means there is nothing to pin: the guides are tracked on a moving master branch, and updating means the git pull described earlier. The last push to the repository was on 2026-10-05. The other limitation is intrinsic to the format. A notebook that calls a hosted API needs network access, a valid account, and usually a key, so it is not a unit test you can run in CI without credentials, and the outputs you see in a committed notebook are a snapshot from the day it was executed rather than a live result. That makes these guides good for learning and awkward as regression tests.

## Conclusion

Adopt these notebooks if you are working with Planet imagery data for the first time and want runnable examples for the Planet APIs instead of piecing the documentation together yourself. Do not adopt them as a library, since nothing here is importable, and do not expect them to run without a Planet account, since every example calls the hosted API and most need a key. Verify first whether the guide you need uses the Planet API key path or the Sentinel Hub client credential path, because those two mechanisms are configured differently and the mismatch is the most common way a notebook fails on first run.

## FAQ

### How do I authenticate the planetlabs/notebooks examples?

Most notebooks read a Planet API key that you export as PL_API_KEY and pick up in Python with os.getenv, while some authenticate through a web login. Notebooks that use the Sentinel Hub Python SDK need a client_id and client_secret instead, and that SDK does not share credentials with the Planet APIs.

### How do I run the Planet notebooks in Docker?

Build the image with docker build -t planet-notebooks planet-notebook-docker/ from the repository root, then run the container with the port mapping, the volume mount and the key passed as PL_API_KEY, and open the printed URL at localhost:8888 in a browser.

### Why do the planetlabs/notebooks notebooks not work with my exported API key?

Check which SDK the notebook uses. Notebooks built on the Sentinel Hub Python SDK need an OAuth client id and secret from the account manager application, and they do not read the Planet API key environment variable.

### Do I need Docker to use the planetlabs/notebooks guides?

No, Docker is listed as optional. The container exists because the notebooks depend on a stack that is hard to configure by hand, and the documentation says you can set up your own environment instead, using the same clone and API key steps.

## Sources

- [Issues](https://github.com/planetlabs/notebooks/issues)
- [License: Apache-2.0](https://github.com/planetlabs/notebooks/blob/master/LICENSE)
- [planetlabs/notebooks on GitHub](https://github.com/planetlabs/notebooks)
- [Project website](https://developers.planet.com/)
- [README](https://github.com/planetlabs/notebooks/blob/master/README.md)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/planetlabs-notebooks