Installation

Requirements

Phi-Down requires:

  • Python 3.10 or newer

  • s5cmd on your PATH for S3 downloads

  • Copernicus Data Space credentials for authenticated downloads

  • PhiSat-2 INSULA credentials if you plan to use --provider phisat2

Install from PyPI

Install the base package:

pip install phidown

Install optional feature groups as needed:

# Interactive plotting and footprint maps
pip install "phidown[viz]"

# AIS download and filtering support
pip install "phidown[ais]"

# Notebook-oriented dependencies
pip install "phidown[jupyter_env]"

# Development, tests, and documentation
pip install "phidown[dev,test,docs]"

Optional Dependency Groups

Phi-Down exposes these optional dependency groups in pyproject.toml:

  • viz: Folium, raster/plotting, and map visualization helpers

  • ais: AIS download support, including spatial filtering dependencies

  • jupyter_env: Jupyter widgets and notebook integrations

  • dev: Development tools such as pytest and flake8

  • test: Test-only dependencies used by the local suite

  • docs: Sphinx and related documentation tooling

Install from Source

Using pip:

git clone https://github.com/ESA-PhiLab/phidown.git
cd phidown
pip install -e .

With optional extras:

pip install -e ".[viz,ais,dev,test,docs]"

Using PDM

For local development, PDM matches the repository setup:

git clone https://github.com/ESA-PhiLab/phidown.git
cd phidown
pdm install

To include optional groups:

pdm install -G viz -G ais -G dev -G test -G docs -G jupyter_env

Install s5cmd

Phi-Down uses s5cmd for S3 transfers. Install it separately if you plan to download data:

brew install peak/tap/s5cmd

or

go install github.com/peak/s5cmd/v2@latest

Then verify:

s5cmd version

Configure .s5cfg

Phi-Down uses a shared .s5cfg file for both CDSE and PhiSat-2 credentials. Keep the existing [default] block for CDSE, then insert the [phisat2] block directly below it.

Recommended template:

[default]
aws_access_key_id = your_access_key
aws_secret_access_key = your_secret_key
aws_region = eu-central-1
host_base = eodata.dataspace.copernicus.eu
host_bucket = eodata.dataspace.copernicus.eu
use_https = true
check_ssl_certificate = true

[phisat2]
username = your_email@example.com
password = your_password
base_url = https://phisat2.insula.earth
api_base = https://phisat2.insula.earth/secure/api/v2.0
authorization_endpoint = https://identity.insula.earth/realms/phisat2/protocol/openid-connect/auth
token_endpoint = https://identity.insula.earth/realms/phisat2/protocol/openid-connect/token
redirect_uri = http://localhost:9207/auth
client_id = api-client

Guidelines:

  • Keep the section names as shown: [default] for CDSE and [phisat2] for INSULA.

  • Store the file in the working directory as .s5cfg if you want to rely on Phi-Down defaults.

  • If you keep credentials elsewhere, pass the path explicitly with -c/--config-file in the CLI or config_file=... in Python.

  • Keep host_base and host_bucket aligned with the CDSE endpoint shown above.

  • The [phisat2] values can usually stay at their defaults except for username and password.

  • Phi-Down parses this file itself and then uses the provider-specific section it needs at runtime.

  • Avoid committing the file to git. Add .s5cfg to your local ignore rules if needed.

  • Rotate credentials in the CDSE S3 key manager if a file is exposed or copied to an untrusted environment.

Example custom path usage:

phidown --name PRODUCT_NAME -o ./data -c ~/.config/phidown/cdse.s5cfg

from pathlib import Path
from phidown import CopernicusDataSearcher

searcher = CopernicusDataSearcher()
searcher.download_product(
    eo_product_name="PRODUCT_NAME",
    output_dir="./data",
    config_file=str(Path.home() / ".config/phidown/cdse.s5cfg"),
)

Verification

Check that the package imports and reports the expected version:

import phidown
print(phidown.__version__)

from phidown import CopernicusDataSearcher
searcher = CopernicusDataSearcher()
print(type(searcher).__name__)

Troubleshooting

s5cmd: command not found

Install s5cmd and make sure it is available on your PATH.

Missing optional dependencies

Install the relevant extra, such as phidown[viz] or phidown[ais].

Import errors in notebooks

Install phidown[jupyter_env] for widget and notebook integrations.

Authentication failures

Recreate the relevant provider section in .s5cfg. Use fresh Copernicus Data Space S3 credentials for [default] or update the PhiSat-2 INSULA username/password in [phisat2] before retrying.