Context

The Copernicus Marine Toolbox has been developed to enable users browsing and downloading easily all the products of the Copernicus Marine Data Store.

In this article, we will show how to install the Copernicus Marine Toolbox (available as CLI or Python API) for mamba|conda , pip and docker-based users, and how to upgrade to the latest version.

ℹ️ The Copernicus Marine Toolbox is available in version 1.3.5.

⚠️ The Copernicus Marine Toolbox is compatible with Windows, Mac and Linux operating systems that run Python version 3.9 to 3.12. Pre-release versions of the Toolbox are also available on PyPI and can be install via pip install "copernicusmarine>=2.0.0a0". It is not recommended to install a pre-release version, except for testing purpose.

Install the Toolbox

Depending on the users' preference, several mutually exclusive methods exist to install the Copernicus Marine Toolbox. Only one method should be chosen.

Installation using `mamba` | `conda`

💡Copernicus Marine Pro Tip: we recommend always creating and working on isolated environments using Mamba, before starting any package installation, to avoid causing interference or problems with the host system.

The copernicusmarine Toolbox is available on Anaconda through the conda-forge channel. In the below commands, you can replace mamba by conda if you still haven't installed it.

Here's a quick video on the Copernicus Marine Toolbox installation process, following the steps detailed below.

Step 1. Open the Miniforge Prompt to create a new environment (could be anything, but let's call it copernicusmarine) and install the copernicusmarine Toolbox from conda-forge:

mamba create --name copernicusmarine conda-forge::copernicusmarine --yes

Step 2. Activate the newly created environment (called copernicusmarine) to use the Toolbox (either for the CLI or PythonAPI):

mamba activate copernicusmarine

Step 3. Run the copernicusmarine Toolbox, depending on the interface:

Command Line Interface (CLI)

copernicusmarine describe --overwrite-metadata-cache > catalog.json

Python Libary (API)

import copernicusmarine
catalog = copernicusmarine.describe(overwrite_metadata_cache=True)

Installation using `pip`

For users preferring pip, within an already isolated environment (with uv, pipx, pipenv, poetry, pyenv, venv, virtualenv, etc.), the copernicusmarine Toolbox is also available on PyPI and can be installed by following these steps:

Step 1. Install the copernicusmarine Toolbox from PyPI:

python -m pip install copernicusmarine

Step 2. Run the copernicusmarine Toolbox, depending on the interface:

Command Line Interface (CLI)

copernicusmarine describe --overwrite-metadata-cache > catalog.json

Python Libary (API)

import copernicusmarine
catalog = copernicusmarine.describe(overwrite_metadata_cache=True)

Installation using `docker`

For users preferring docker-based toolkits, a container image is available on the dockerhub. To use it, follow these steps:

Step 1. Pull the copernicusmarine Toolbox as a container image:

docker pull copernicusmarine/copernicusmarine

Step 2. Run the copernicusmarine Toolbox:

docker run --interative --tty copernicusmarine/copernicusmarine --help

Installation kernel for notebooks

If you wish to use your environment in a notebook, you must first create the kernel. To do this, enter the lines below in your CLI:

mamba activate copernicusmarine

mamba install ipykernel

python -m ipykernel install --user --name copernicusmarine --display-name "CMT_Kernel"

All you have to do is restart your notebook to see your kernel appear!

Upgrade the Toolbox

💡Copernicus Marine Pro Tip: when it comes to updating a package, it's advised to stick to the method used for the installation (either mamba|conda or pip but not a mix). For example:

If you installed the Toolbox with pip, then upgrade with pip
If you installed with mamba|conda, then upgrade with mamba|conda
If you installed with mamba|conda and a yaml file which itself indexed pip and copernicusmarine via pip, then upgrade with pip

Cleaning cache

If you are using an earlier version of the Toolbox, we encourage you to first delete the folders below before proceeding with the update:

on UNIX platforms:
- Before version 1.0.0:
  - $HOME/.copernicus-marine-client (or .copernicus_marine_client)
  - $HOME/.cachier
- After version 1.0.0:
  - $HOME/.copernicusmarine
on Windows platforms:
- Before version 1.0.0:
  - %USERPROFILE%\.copernicus-marine-client (or .copernicus_marine_client)
  - %USERPROFILE%\.cachier
- After version 1.0.0:
  - %USERPROFILE%\.copernicusmarine

Upgrade using `mamba` | `conda`

To get the latest version of the Copernicus Marine Toolbox as installed in the previous step and considering an environment whose name is copernicusmarine, then run the following command (replace mamba by conda if necessary):

mamba update --name copernicusmarine copernicusmarine --yes

⚠️ Please be aware the newest version of the copernicusmarine Toolbox usually takes a few hours to appear on Anaconda after its release on PyPI.

Upgrade using `pip`

To get the latest version of the Copernicus Marine Toolbox as installed in the previous step, then run:

python -m pip install copernicusmarine --upgrade

Checking the version

To check the version of the Toolbox, depending on the interface:

Command Line Interface (CLI)

copernicusmarine --version

Python Library (API)

import copernicusmarine
print(copernicusmarine.__version__)

💡 Copernicus Marine Pro Tip: if you are working in a Jupyter/IPython notebook, remember to restart the kernel after upgrading the Toolbox!

Toolbox configuration

⚠️ Please, keep in mind that the following code lines are case-sensitive.

Network Rules

Endpoints permission

For users depending on company network rules, they might need to contact the administrator in their company, to declare the below endpoints (domain names under HTTPS protocol) that will be used by the Copernicus Marine Toolbox during its execution:

Copernicus Marine Authentication Service
- https://cmems-cas.cls.fr

Copernicus Marine Metadata and Data Service
- https://s3.waw3-1.cloudferro.com
- https://s3.waw2-1.cloudferro.com

SSL exchanges

You can configure the Toolbox to disable verification of SSL exchanges performed by the Toolbox, by adding the COPERNICUSMARINE_DISABLE_SSL_CONTEXT environment variable to True:

on UNIX platforms: export COPERNICUSMARINE_DISABLE_SSL_CONTEXT=True
on Windows platforms: set COPERNICUSMARINE_DISABLE_SSL_CONTEXT=True

System host environment variable

To do HTTP calls, the Copernicus Marine Toolbox uses two Python libraries: requests and aiohttp. By default, those libraries will have the trust_env value set to True. If you want to deactivate this, you can set the COPERNICUSMARINE_TRUST_ENV environment variable to False:

on UNIX platforms: export COPERNICUSMARINE_TRUST_ENV=False
on Windows platforms: set COPERNICUSMARINE_TRUST_ENV=False

This can be useful to deactivate automated reading of configuration files such as .netrc file, as it has been reported that specific lines (i.e. default login anonymous password user@site) are incompatible with S3 connection required by the Toolbox.

Proxy

To use proxies, as described in the aiohttp documentation you can use two options:

set the HTTPS_PROXY environment variable. For ex: HTTPS_PROXY="http://user:pass@some.proxy.com". It works even with COPERNICUSMARINE_TRUST_ENV=False
use a .netrc file, but be aware that having a line default login anonymous password user@site is incompatible with S3 connection required by the Toolbox. Also, note that if you have COPERNICUSMARINE_TRUST_ENV=True (the default value) then if the NETRC environment variable is set with a specified location, the .netrc file will be read from the specified location there rather than from the user's home folder default location.

Number of concurrent requests

The Toolbox parses the Copernicus Marine Data Store catalogue requiring many HTTP requests. For that, it uses asynchronous calls. On some machines (with low capacity), it might bring some challenges due to the inherent Input/Output network consumption.

To limit the number of requests at the same time, you can use COPERNICUSMARINE_MAX_CONCURRENT_REQUESTS. The default value is 15 and minimum value is 1.

Example:

on UNIX platforms: export COPERNICUSMARINE_MAX_CONCURRENT_REQUESTS=7
on Windows platforms: set COPERNICUSMARINE_MAX_CONCURRENT_REQUESTS=7

📌 Note: it concerns only the step to parse the catalogue, i.e. the describe command. It does not apply when requesting the data chunks via subset or when downloading files or listing files via get. An evolution has been recorded and will be implemented at a later stage.

Cache usage

The cachier library is used for caching part of the requests (as the result of describe or login feature). By default, the cache will be located in the user's home folder. If you need to change the location of the cache, you can set the environment variable COPERNICUSMARINE_CACHE_DIRECTORY to point to the desired directory:

on UNIX platforms: export COPERNICUSMARINE_CACHE_DIRECTORY=/tmp
on Windows platforms: set COPERNICUSMARINE_CACHE_DIRECTORY=C:\temp

💡Copernicus Marine Pro Tip: setting the cache to the /tmp folder is highly recommended for HPC users and alike, to avoid the LockException error.

Credentials

If you are setting up a machine-to-machine pipeline with a fully autonomous script or pipeline, then it could be judicious to set the credentials as environment variables:

on UNIX platforms:
- export COPERNICUSMARINE_SERVICE_USERNAME=your_username
- export COPERNICUSMARINE_SERVICE_PASSWORD=your_password
on Windows platforms:
- set COPERNICUSMARINE_SERVICE_USERNAME=your_username
- set COPERNICUSMARINE_SERVICE_PASSWORD=your_password

Once done, the credentials are automatically read without having to specify anything else in your data request using the copernicusmarine Toolbox:

Command Line Interface (CLI)

copernicusmarine subset -i cmems_mod_glo_phy-thetao_anfc_0.083deg_P1D-m -x -9.27 -X -9.27 -y 33.08 -Y 33.08 -z 0 -Z 0 --force-download

Python Library (API)

import copernicusmarine
copernicusmarine.subset(
dataset_id="cmems_mod_glo_phy-thetao_anfc_0.083deg_P1D-m",
variables=["thetao"],
minimum_longitude=-9.27,
maximum_longitude=-9.27,
minimum_latitude=33.08,
maximum_latitude=33.08,
minimum_depth=0,
maximum_depth=0,
force_download=True
)

💡 Copernicus Marine Pro Tip: defining credentials as environment variables has the same advantages as the login function, but in addition it does not create a cache file on the machine's hard disk.

Toolbox version management

It uses the semantic versioning X.Y.Z → for example 1.2.3

X is bumped on demand to highlight a new significant feature or for communication purposes.
Y is bumped on breaking changes.
Z is bumped on minor non-breaking changes.

What's next?

Now that you've installed and configured the Toolbox, explore its main functionalities.

If you are facing any issues with any step of this article, then please:

check first the troubleshootings
then feel free to chat with us using the widget at the bottom right corner

How to create a local Python environment for your Copernicus Marine projects?

Copernicus Marine Toolbox - Introduction

Copernicus Marine Toolbox - Installation

Copernicus Marine Toolbox - Credentials configuration

How to download data via the Copernicus Marine Toolbox in Julia?

Copernicus Marine Toolbox - Installation (v1.3.5)

Context

Install the Toolbox

Installation using mamba | conda

Installation using pip

Installation using docker

Installation kernel for notebooks

Upgrade the Toolbox

Cleaning cache

Upgrade using mamba | conda

Upgrade using pip

Checking the version

Toolbox configuration

Network Rules

Endpoints permission

SSL exchanges

System host environment variable

Proxy

Number of concurrent requests

Cache usage

Credentials

Toolbox version management

What's next?

Installation using `mamba` | `conda`

Installation using `pip`

Installation using `docker`

Upgrade using `mamba` | `conda`

Upgrade using `pip`