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

[maltfield]

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.

[aagbsn]

Thank you for reporting this issue

[aagbsn]

Need to cut a release to close this; pip install oonidata doesn't yet work