# Installation
PODPAC is available for Windows, Mac, and Linux.
Select the installation method the best suits your development environment:
- [pip](#install-with-pip): Recommended for most users
- [Docker](#docker): For use in containers
- [Install from source](#install-from-source): For development
- [Windows Standalone distribution](#standalone-windows-distribution): Includes Python and all dependencies
## Install with pip
### Requirements
Confirm you have the required dependencies installed on your computer:
- [Python](https://www.python.org/) (3.6 or later) — [Anaconda Python Distribution](https://www.anaconda.com/distribution/#download-section) recommended
- See [operating system requirements](dependencies.html#os-specific-requirements)
### Environment
If using Anaconda Python (recommended for Windows), create a PODPAC dedicated Anconda environment:
```
# create environment
$ conda create -n podpac python=3
# activate environment
$ conda activate podpac
```
If using a non-Anaconda Python distribution, create a PODPAC dedicated virtual environment:
```
# create environment in
using virtualenv
$ python3 -m venv
# activate environment
$ source /bin/activate
# Create environment named `podpac` using pyenv
$ pyenv virtualenv 3.8.6 podpac
$ pyenv activate podpac
```
### Install
#### Windows Pre-Installation Instructions with Anaconda
Some packages are simpler to install through `conda` compared to `pip` on Windows. NOTE: These
instructions tend to change based on the specific version of `conda`. Substituting which packages
are installed from `conda-forge` vs the `default` `conda` channel can usually result in a
functional installation.
For a full PODPAC installation pre-install the
following packages in a clean `conda` environment:
```bash
# Install core dependencies
> conda install matplotlib>=2.1 numpy>=1.14 scipy>=1.0 traitlets>=4.3 xarray>=0.10 ipython psutil requests>=2.18 owslib beautifulsoup4>=4.6 h5py>=2.9 lxml>=4.2 zarr>=2.3 intake>=0.5 boto3>=1.4 s3fs>=0.2 numexpr>=2.6 jupyterlab ipywidgets nodejs
> conda install pyproj>=2.2 rasterio>=1.0 ipympl ipyleaflet -c conda-forge
# Set up jupyter lab extensions
> jupyter labextension install @jupyter-widgets/jupyterlab-manager
> jupyter labextension install jupyter-leaflet
> jupyter labextension install jupyter-matplotlib
> jupyter nbextension enable --py widgetsnbextension
> jupyter lab build
# clean conda environment (optional)
> conda clean -a -y
```
#### All Operating systems
After activating the environment, install using `pip` with one of the following commands:
```
$ pip install podpac # base installation
$ pip install podpac[datatype] # install podpac and optional data handling dependencies
$ pip install podpac[notebook] # install podpac and optional notebook dependencies
$ pip install podpac[aws] # install podpac and optional aws dependencies
$ pip install podpac[algorithm] # install podpac and optional algorithm dependencies
$ pip install podpac[all] # install podpac and all optional dependencies
```
See [Optional Dependencies](dependencies.html#optional-dependencies) more information on optional PODPAC dependencies.
## Docker
This guide assumes you have a working installation of Docker on your computer or server.
- [Install for Linux](https://docs.docker.com/install/linux/docker-ce/debian/)
- [Install for Mac](https://docs.docker.com/docker-for-mac/install/)
- [Install for Windows](https://docs.docker.com/docker-for-windows/install/)
Once you have Docker installed, the following steps will allow you to run PODPAC within an interactive Docker shell:
- Download the [PODPAC Dockerfile](https://github.com/creare-com/podpac/blob/master/Dockerfile) from the repository
- From the directory where you downloaded the `Dockerfile`, run:
```
# build the docker image with the tag `podpac`
$ docker build -t podpac .
```
- Run the built image
```
# run the docker image in an interactive shell
$ docker run -i -t podpac
```
## Standalone Windows Distribution
### Windows 10
The Window 10 standalone distribution requires no pre-installed operating system or external dependencies.
- Download the latest Window 10 standalone distribution
- [https://s3.amazonaws.com/podpac-s3/releases/PODPAC_latest_install_windows10.zip](https://s3.amazonaws.com/podpac-s3/releases/PODPAC_latest_install_windows10.zip)
- For older versions, substitute `latest` in the url with the version number, i.e. `PODPAC_1.2.0_install_windows10.zip`
- Once downloaded, extract the zip file into a folder on your machine.
- We recommend expanding it near the root of your drive (e.g. `C:\PODPAC`) due to long file paths that are part of the installation.
Once the folder is unzipped:
- To run an IPython session:
- Open a Windows command prompt in this directory
- Run the `run_ipython.bat` script
- To open the example [Jupyter notebooks](https://jupyter.org/):
- Double click the file `run_podpac_jupyterlab.bat`
- This will open up a Windows command prompt, and launch a JupyterLab notebook in your default web browser
- To close the notebook, close the browser tab, and close the Windows console
To make this standalone distribution, see the [deploy notes](deploy-notes.md).
## Install from Source
### Requirements
Confirm you have the required dependencies installed on your computer:
- [git](https://git-scm.com/)
- [Python](https://www.python.org/) (3.6 or later)
- We recommend the [Anaconda Python Distribution](https://www.anaconda.com/distribution/#download-section)
- See [operating system requirements](dependencies.html#os-specific-requirements#os-specific-requirements)
### Environment
If using Anaconda Python, create a PODPAC dedicated Anconda environment:
```
# create environment with all `anaconda` packages
$ conda create -n podpac python=3 anaconda
# activate environment
$ conda activate podpac
```
If using a non-Anaconda Python distribution, create a PODPAC dedicated virtual environment:
```
# create environment in
$ python3 -m venv
# activate environment
$ source /bin/activate
```
### Install
After activating the virtual environment, clone the [podpac repository](https://github.com/creare-com/podpac) onto your machine:
```
$ cd
$ git clone https://github.com/creare-com/podpac.git
$ cd podpac
```
By default, PODPAC clones to the `master` branch, which is the latest stable release.
To use a previous release, checkout the `tags/` reference.
For bleeding edge, checkout the `develop` branch.
```
$ git fetch origin # fetch all remote branches
$ git checkout -b release/ tags/ # checkout specific release
$ git checkout -b develop origin/develop # latest stable version
```
From the root of the git repository, install using `pip` with one of the following commands:
```
$ pip install -e . # base installation
$ pip install -e .[datatype] # install podpac and optional data handling dependencies
$ pip install -e .[notebook] # install podpac and optional notebook dependencies
$ pip install -e .[aws] # install podpac and optional aws dependencies
$ pip install -e .[algorithm] # install podpac and optional algorithm dependencies
$ pip install -e .[all] # install podpac and all optional dependencies
```
See [Optional Dependencies](dependencies.html#optional-dependencies) more information on optional PODPAC dependencies.
To install PODPAC and keep installation up to date with local changes, use the option `-e` when installing:
```
$ pip install -e . # install podpac with only core dependencies
$ pip install -e .[devall] # install podpac and all optional dependencies
```
## Common Issues
### Rasterio
Some users may experience issues installing [rasterio](https://rasterio.readthedocs.io/en/latest/installation.html) (included in the `datatype` and `all` installations).
If you encounter issues, we recommend trying to install [rasterio](https://rasterio.readthedocs.io/en/latest/installation.html) into your active Python environment, then re-installing `podpac`.
### UnicodeDecodeError
```
UnicodeDecodeError: 'ascii' codec can't decode byte 0xe2 in position 13: ordinal not in range(128)*
```
Some linux users may encounter this when using Ubuntu and Python 3.6.
See this [stack overflow answer](https://stackoverflow.com/a/49127686) for a solution.
### Python.h
```
psutil/_psutil_common.c:9:10: fatal error: Python.h: No such file or directory
#include
^~~~~~~~~~
compilation terminated.
error: command 'x86_64-linux-gnu-gcc' failed with exit status 1
```
You are missing the `python-dev` header and static files.
See this [stack overflow answer](https://stackoverflow.com/a/21530768) for the appropriate solution.