Installing Copernicus Marine Toolbox

There are several ways to install or use the Copernicus Marine Toolbox:

Alternatively, you can use a binary.

Note

Requires Python >=3.9.

Note

Note that the use of xarray<2024.7.0 with numpy>=2.0.0 leads to inconsistent results. See later on this page for more details.

Via pip

If you already have an environment (safer to clone it), the package can be installed using the pip command from the Python Package Index:

python -m pip install copernicusmarine

And to upgrade the package to the newest available version, run:

python -m pip install copernicusmarine --upgrade

Via mamba | conda (conda-forge channel)

A conda package is available on Anaconda.

You can install it using mamba (or conda) through the conda-forge channel with the following command:

mamba install conda-forge::copernicusmarine --yes

To upgrade the Toolbox with mamba (or conda):

mamba update --name copernicusmarine copernicusmarine --yes

Or using conda:

conda install -c conda-forge copernicusmarine

Via docker

A Docker image is also available on the copernicusmarine dockerhub repository.

First step is to pull the container image:

docker pull copernicusmarine/copernicusmarine:latest

Then run it:

docker run -it --rm copernicusmarine/copernicusmarine --version

Create an account on Copernicus Marine website

To be able to download Copernicus Marine data, you need to have an account on the Copernicus Marine website. You can create an account on the Copernicus Marine registration page.

Use the Copernicus Marine Toolbox binaries

In the release page you can access the binaries of the latest releases.

To download directly the latest stable releases:

Once downloaded for the specific platform, you can use the Toolbox by running the binary as follows:

In mac-os or linux:

./copernicusmarine_macos-x86_64.cli --help
# or for example a subset command
./copernicusmarine_macos-x86_64.cli subset --create-template
./copernicusmarine_macos-x86_64.cli subset --request-file subset_template.json

Note

You might have to update the permissions of the binary to be able to execute it with linux:

chmod +rwx copernicusmarine_linux-glibc-2.35.cli

And from a Windows os (cmd):

copernicusmarine.exe --help
# or for example a subset command
copernicusmarine.exe subset --create-template
copernicusmarine.exe subset --request-file subset_template.json

Note

For the Linux binaries you need a version of Glibc higher than the one the binary has. To check your version of Glibc, use ldd --version in your terminal.

Note

The Linux binaries are tested with Ubuntu machines.

Note

The MacOS binaries might have to be authorized to run in your system. Follow the steps in the popup window to authorize the binary.

Dependencies

The Copernicus Marine Toolbox has the following dependencies:

The Copernicus Marine Toolbox uses the xarray library to handle the data when using the subset command in the majority of cases. There are some compatibility issues with the latest versions of xarray and numpy:

  • xarray<2024.7.0 with numpy>=2.0.0 leads to inconsistent results. See this issue: xarray issue 1.

  • xarray<2024.10.0 with numpy>=2.0.0 leads to some time overhead. See this issue: xarray issue 2.

For zarr>=3.0.0:

  • If you want to use zarr>=v3, you need to use xarray>=2025.3.0.

  • If you want to use zarr>=3.0.9, you should also update the Copernicus Marine Toolbox to copernicusmarine>=2.2.0.

Also to convert subsetted data to NetCDF format the toolbox uses the xarray.Dataset.to_netcdf and h5netcdf library as the backend.

Note

The h5netcdf library is not compatible with the NetCDF3 format. If you need to save files in NetCDF3 format please just manually install netcdf4 library (see also netCDF4 page):

# with conda | mamba | micromamba
conda install -c conda-forge netCDF4
# or add it to you environment.yml file

# with pip
python -m pip install netCDF4

The docker image of the Toolbox should already have the netcdf4 library installed.

If you use subprocess.run or similar, or you are on Windows, and with version 8.2.0 of click, it would create a bug where certain flags would not be taken into account. Hence, the Toolbox is incompatible with click==8.2.0. Please check this click issue for more information.

Domains required by the Copernicus Marine Toolbox

To be able to use the Copernicus Marine Services, you need to be able to access those domains:

  • https://cmems-cas.cls.fr: for the old authentication process.

  • https://auth.marine.copernicus.eu: for the new authentication process.

  • https://s3.waw3-1.cloudferro.com: for the data and the metadata.

  • https://s3.waw4-1.cloudferro.com: for the data and the metadata.

  • https://stac.marine.copernicus.eu: for the metadata.

To check if you are able to access https://s3.waw3-1.cloudferro.com, for example, you can do the following steps.

First, open a Python console in the same environment as you would run your script:

python

Then, run a requests and check that the result is as expected:

import requests

# you can pass here proxies and ssl configuration if needed
response = requests.get(
    "https://s3.waw3-1.cloudferro.com/mdl-metadata/mdsVersions.json"
)
response.raise_for_status()

print(response.json())

# you should get something like:
# {'systemVersions': {'mds': '1.0.0', [..] 'mds/serverlessArco/meta': '>=1.2.2'}}
# and no error should be raised

For the authentication, check that you can run the login command. If you have an error related to HTTP calls or internet connection, please check with your IT support.