[docs] fix install instructions for oonidata (command not found)

This ticket is a bug report in the documentation of oonidata

• https://docs.ooni.org/data/oonidata/

...getting started is easy, run:

pip install oonidata

You will then be able to download measurements via:

oonidata sync --probe-cc IT --start-day 2022-10-01 --end-day 2022-10-02 --output-dir measurements/

Unfortunately, these commands fail, as attempting to follow the above documentation produces an error.

Problem

The following execution uses docker to consistently reproduce the error in Debian 12

sudo apt-get install docker.io
sudo bash -c 'gpasswd -a "${SUDO_USER}" docker'
su - `whoami`

docker run --rm -it --entrypoint /bin/bash debian:bookworm-slim

apt update
apt install python3-pip python3-virtualenv

python3 -m virtualenv /tmp/virtualenv
source /tmp/virtualenv/bin/activate

pip install oonidata
oonidata sync --probe-cc IT --start-day 2022-10-01 --end-day 2022-10-02 --output-dir measurements/

Example

Below is an example exeuction of the above commands

user@disp8426:~$ sudo apt-get install docker.io
...
user@disp8426:~$ 

user@disp8426:~$ sudo bash -c 'gpasswd -a "${SUDO_USER}" docker'
Adding user user to group docker
user@disp8426:~$ 

user@disp8426:~$ su - `whoami`
user@disp8426:~$ 

user@disp8426:~$ docker run --rm -it --entrypoint /bin/bash debian:bookworm-slim
Unable to find image 'debian:bookworm-slim' locally
bookworm-slim: Pulling from library/debian
4831516dd0cb: Pull complete 
Digest: sha256:98f4b71de414932439ac6ac690d7060df1f27161073c5036a7553723881bffbe
Status: Downloaded newer image for debian:bookworm-slim
root@53441006b165:/#      
     
root@53441006b165:/# apt update
Get:1 http://deb.debian.org/debian bookworm InRelease [151 kB]
Get:2 http://deb.debian.org/debian bookworm-updates InRelease [55.4 kB]
Get:3 http://deb.debian.org/debian-security bookworm-security InRelease [48.0 kB]
Get:4 http://deb.debian.org/debian bookworm/main amd64 Packages [8792 kB]
Get:5 http://deb.debian.org/debian bookworm-updates/main amd64 Packages [6924 B]
Get:6 http://deb.debian.org/debian-security bookworm-security/main amd64 Packages [297 kB]
Fetched 9350 kB in 7s (1429 kB/s)                                              
Reading package lists... Done
Building dependency tree... Done
Reading state information... Done
1 package can be upgraded. Run 'apt list --upip install oonidatapgradable' to see it.
root@53441006b165:/# 

root@53441006b165:/# apt install python3-pip python3-virtualenv
...
root@53441006b165:/# 

root@53441006b165:/# python3 -m virtualenv /tmp/virtualenv
created virtual environment CPython3.11.2.final.0-64 in 208ms
  creator CPython3Posix(dest=/tmp/virtualenv, clear=False, no_vcs_ignore=False, global=False)
  seeder FromAppData(download=False, pip=bundle, setuptools=bundle, wheel=bundle, via=copy, app_data_dir=/root/.local/share/virtualenv)
    added seed packages: pip==23.0.1, setuptools==66.1.1, wheel==0.38.4
  activators BashActivator,CShellActivator,FishActivator,NushellActivator,PowerShellActivator,PythonActivator
root@53441006b165:/# 

root@53441006b165:/# source /tmp/virtualenv/bin/activate
(virtualenv) root@53441006b165:/# 

(virtualenv) root@53441006b165:/# pip install oonidata
Collecting oonidata
  Downloading oonidata-0.3.0-py2.py3-none-any.whl (40 kB)
     ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 40.1/40.1 kB 125.2 kB/s eta 0:00:00
Collecting boto3~=1.24
  Downloading boto3-1.42.52-py3-none-any.whl (140 kB)
     ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 140.6/140.6 kB 171.5 kB/s eta 0:00:00
Collecting click-loglevel~=0.5.0
  Downloading click_loglevel-0.5.1-py3-none-any.whl (5.3 kB)
Collecting click~=8.0.0
  Downloading click-8.0.4-py3-none-any.whl (97 kB)
     ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 97.5/97.5 kB 285.1 kB/s eta 0:00:00
Collecting cryptography~=38.0.3
  Downloading cryptography-38.0.4-cp36-abi3-manylinux_2_28_x86_64.whl (4.2 MB)
     ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 4.2/4.2 MB 443.3 kB/s eta 0:00:00
Collecting lxml~=4.9
  Downloading lxml-4.9.4-cp311-cp311-manylinux_2_28_x86_64.whl (7.9 MB)
     ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 7.9/7.9 MB 1.8 MB/s eta 0:00:00
Collecting lz4~=4.0
  Downloading lz4-4.4.5-cp311-cp311-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl (1.4 MB)
     ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 1.4/1.4 MB 3.0 MB/s eta 0:00:00
Collecting mashumaro~=3.0
  Downloading mashumaro-3.20-py3-none-any.whl (94 kB)
     ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 94.9/94.9 kB 3.3 MB/s eta 0:00:00
Collecting orjson~=3.8
  Downloading orjson-3.11.7-cp311-cp311-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (133 kB)
     ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 133.4/133.4 kB 3.3 MB/s eta 0:00:00
Collecting pyopenssl~=22.1
  Downloading pyOpenSSL-22.1.0-py3-none-any.whl (57 kB)
     ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 57.0/57.0 kB 2.9 MB/s eta 0:00:00
Collecting pyyaml~=6.0
  Downloading pyyaml-6.0.3-cp311-cp311-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl (806 kB)
     ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 806.6/806.6 kB 2.7 MB/s eta 0:00:00
Collecting requests~=2.27
  Downloading requests-2.32.5-py3-none-any.whl (64 kB)
     ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 64.7/64.7 kB 3.0 MB/s eta 0:00:00
Collecting tabulate~=0.9.0
  Downloading tabulate-0.9.0-py3-none-any.whl (35 kB)
Collecting tqdm~=4.64
  Downloading tqdm-4.67.3-py3-none-any.whl (78 kB)
     ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 78.4/78.4 kB 3.2 MB/s eta 0:00:00
Collecting botocore<1.43.0,>=1.42.52
  Downloading botocore-1.42.52-py3-none-any.whl (14.6 MB)
     ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 14.6/14.6 MB 2.3 MB/s eta 0:00:00
Collecting jmespath<2.0.0,>=0.7.1
  Downloading jmespath-1.1.0-py3-none-any.whl (20 kB)
Collecting s3transfer<0.17.0,>=0.16.0
  Downloading s3transfer-0.16.0-py3-none-any.whl (86 kB)
     ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 86.8/86.8 kB 2.7 MB/s eta 0:00:00
Collecting cffi>=1.12
  Downloading cffi-2.0.0-cp311-cp311-manylinux2014_x86_64.manylinux_2_17_x86_64.whl (215 kB)
     ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 215.6/215.6 kB 3.3 MB/s eta 0:00:00
Collecting typing_extensions>=4.14.0
  Downloading typing_extensions-4.15.0-py3-none-any.whl (44 kB)
     ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 44.6/44.6 kB 2.4 MB/s eta 0:00:00
Collecting charset_normalizer<4,>=2
  Downloading charset_normalizer-3.4.4-cp311-cp311-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl (151 kB)
     ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 151.6/151.6 kB 171.0 kB/s eta 0:00:00
Collecting idna<4,>=2.5
  Downloading idna-3.11-py3-none-any.whl (71 kB)
     ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 71.0/71.0 kB 2.2 MB/s eta 0:00:00
Collecting urllib3<3,>=1.21.1
  Downloading urllib3-2.6.3-py3-none-any.whl (131 kB)
     ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 131.6/131.6 kB 2.0 MB/s eta 0:00:00
Collecting certifi>=2017.4.17
  Downloading certifi-2026.1.4-py3-none-any.whl (152 kB)
     ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 152.9/152.9 kB 2.1 MB/s eta 0:00:00
Collecting python-dateutil<3.0.0,>=2.1
  Downloading python_dateutil-2.9.0.post0-py2.py3-none-any.whl (229 kB)
     ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 229.9/229.9 kB 2.5 MB/s eta 0:00:00
Collecting pycparser
  Downloading pycparser-3.0-py3-none-any.whl (48 kB)
     ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 48.2/48.2 kB 2.1 MB/s eta 0:00:00
Collecting six>=1.5
  Downloading six-1.17.0-py2.py3-none-any.whl (11 kB)
Installing collected packages: urllib3, typing_extensions, tqdm, tabulate, six, pyyaml, pycparser, orjson, lz4, lxml, jmespath, idna, click, charset_normalizer, certifi, requests, python-dateutil, mashumaro, click-loglevel, cffi, cryptography, botocore, s3transfer, pyopenssl, boto3, oonidata
Successfully installed boto3-1.42.52 botocore-1.42.52 certifi-2026.1.4 cffi-2.0.0 charset_normalizer-3.4.4 click-8.0.4 click-loglevel-0.5.1 cryptography-38.0.4 idna-3.11 jmespath-1.1.0 lxml-4.9.4 lz4-4.4.5 mashumaro-3.20 oonidata-0.3.0 orjson-3.11.7 pycparser-3.0 pyopenssl-22.1.0 python-dateutil-2.9.0.post0 pyyaml-6.0.3 requests-2.32.5 s3transfer-0.16.0 six-1.17.0 tabulate-0.9.0 tqdm-4.67.3 typing_extensions-4.15.0 urllib3-2.6.3
(virtualenv) root@53441006b165:/# 

(virtualenv) root@53441006b165:/# oonidata sync --probe-cc IT --start-day 2022-10-01 --end-day 2022-10-02 --output-dir measurements/
bash: oonidata: command not found
(virtualenv) root@53441006b165:/# 

(virtualenv) root@53441006b165:/# find / -name oonidata
/tmp/virtualenv/lib/python3.11/site-packages/oonidata
(virtualenv) root@53441006b165:/#

(virtualenv) root@53441006b165:/# /tmp/virtualenv/lib/python3.11/site-packages/oonidata
bash: /tmp/virtualenv/lib/python3.11/site-packages/oonidata: Is a directory
(virtualenv) root@53441006b165:/# 

Solution

The problem appears to be that the pip install oonidata does not create any binary named oonidata

The documentation should be updated such that a user following it can install and use oonidata, without errors.

Open the oonidata documentation at https://docs.ooni.org/data/oonidata/ and reproduce the listed pip install and oonidata sync commands in the Debian 12 virtualenv described in the issue. Check the installed package's available command entry point, update the installation and usage instructions accordingly, and verify that the documented workflow runs without a command-not-found error.