`colab` crashes with `ImportError: cannot import name '_device' from partially initialized module 'zmq.backend.cython'` when a pre-existing `pyzmq<26` is already installed

[Manamama]

Claude below, but I mostly stand by this. In very short, one should best do some:
pip install -U google-colab-cli jupyter_client pyzmq jsonschema to make the current version run:
colab version Version: 0.6.0
and not only install.

Hi — I'm Claude (Anthropic), helping @Manamama .

Summary

colab fails at startup with an ImportError originating in pyzmq's Cython backend, but only when an older pyzmq (e.g. 25.1.1) is already present on the system from an unrelated prior install (commonly via ipykernel, jupyter, or ML tooling like pyannote-audio/whisperx). On a genuinely clean environment, pip install google-colab-cli works fine.

Traceback

Traceback (most recent call last):
  File ".../bin/colab", line 3, in <module>
    from colab_cli.cli import main
  ...
  File ".../jupyter_client/asynchronous/client.py", line 9, in <module>
    import zmq.asyncio
  File ".../zmq/__init__.py", line 103, in <module>
    from zmq import backend
  File ".../zmq/backend/__init__.py", line 31, in <module>
    raise original_error from None
  File ".../zmq/backend/__init__.py", line 26, in <module>
    _ns = select_backend(first)
  File ".../zmq/backend/select.py", line 31, in select_backend
    mod = import_module(name)
  File ".../zmq/backend/cython/__init__.py", line 6, in <module>
    from . import (
ImportError: cannot import name '_device' from partially initialized module 'zmq.backend.cython' (most likely due to a circular import)

Root cause

google-colab-cli (via jupyter-kernel-client → jupyter_client) declares a loose lower bound, pyzmq>=25.0. On install, pip only fetches a new version of a dependency if the currently installed one fails to satisfy the declared bound. If pyzmq 25.1.1 already exists from an earlier install, 25.1.1 >= 25.0 is technically true, so pip leaves it untouched — even though jupyter_client 8.9.1 (which does get freshly installed, since nothing pinned it before) apparently expects Cython backend symbols that only ship in newer pyzmq builds. The combination of "old pyzmq, new jupyter_client" hits an ABI/symbol gap that neither project's individual version bound catches, because each bound was satisfied in isolation.

This is not a fresh-install bug — it's a stale-transitive-dependency bug, only reachable when the environment already has prior Jupyter/ML tooling installed. That's a very common case for this CLI's actual audience (people who'd want a Colab CLI have often already got ipykernel or similar on their machine).

Repro (affected — pre-existing pyzmq 25.1.1)

$ pip show pyzmq
Version: 25.1.1
Required-by: ipykernel, jupyter_client

$ pip install google-colab-cli
...
Successfully installed ... jupyter-client-8.9.1 ... (pyzmq untouched, stays 25.1.1)

$ colab
[traceback above]

Control test — clean environment (works)

To confirm this isn't a general packaging defect, I installed google-colab-cli into an isolated sandbox with no prior Python packages (Python 3.12.3, pip 24.0):

$ pip install google-colab-cli
...
Successfully installed ... jupyter-client-8.9.1 ... pyzmq-27.1.0 ...

$ python3 -c "import zmq; print(zmq.__version__, zmq.zmq_version())"
27.1.0 4.3.5

$ colab --help
Usage: colab [OPTIONS] COMMAND [ARGS]...
Colab CLI
...
[full help output, no error]

With no pre-existing pyzmq to defer to, pip's resolver picked a current build (27.1.0) and everything links cleanly. This confirms the failure is specific to environments carrying an old pyzmq, not a defect in google-colab-cli's dependency graph on first install.

Suggested fixes (any of these would help)

1. Raise the effective floor so a stale pyzmq<26 can't silently satisfy the chain — e.g. bump the jupyter-client/jupyter-kernel-client lower bound to a version that itself requires pyzmq>=26, if that's confirmed as the working boundary.
2. Catch this specific ImportError at CLI startup and print a friendly hint (e.g. pip install --upgrade jupyter_client pyzmq) instead of a raw traceback.
3. Document the known-good minimum versions for anyone hitting this after installing into a non-fresh environment.

Environment (affected machine)

• OS: Zorin OS 16.3 x86_64 (Ubuntu-based)
• Python: 3.12.13
• pyzmq: 25.1.1 (pre-existing, via ipykernel)
• jupyter_client: 8.9.1 (installed fresh by google-colab-cli)
• google-colab-cli: 0.6.0

Happy to provide more detail or test a patched dependency floor if useful.

plus this:

colab
Traceback (most recent call last):
  File "/home/zezen/.local/bin/colab", line 3, in <module>
    from colab_cli.cli import main
  File "/home/zezen/.local/lib/python3.12/site-packages/colab_cli/cli.py", line 26, in <module>
    from colab_cli.commands import session, execution, files, automation, run, utility
  File "/home/zezen/.local/lib/python3.12/site-packages/colab_cli/commands/execution.py", line 16, in <module>
    import nbformat
  File "/home/zezen/.local/lib/python3.12/site-packages/nbformat/__init__.py", line 14, in <module>
    from . import v1, v2, v3, v4
  File "/home/zezen/.local/lib/python3.12/site-packages/nbformat/v4/__init__.py", line 24, in <module>
    from .convert import downgrade, upgrade
  File "/home/zezen/.local/lib/python3.12/site-packages/nbformat/v4/convert.py", line 12, in <module>
    from nbformat import v3, validator
  File "/home/zezen/.local/lib/python3.12/site-packages/nbformat/validator.py", line 17, in <module>
    from .json_compat import ValidationError, _validator_for_name, get_current_validator
  File "/home/zezen/.local/lib/python3.12/site-packages/nbformat/json_compat.py", line 13, in <module>
    import jsonschema
  File "/home/zezen/.local/lib/python3.12/site-packages/jsonschema/__init__.py", line 13, in <module>
    from jsonschema._format import FormatChecker
  File "/home/zezen/.local/lib/python3.12/site-packages/jsonschema/_format.py", line 11, in <module>
    from jsonschema.exceptions import FormatError
  File "/home/zezen/.local/lib/python3.12/site-packages/jsonschema/exceptions.py", line 15, in <module>
    from referencing.exceptions import Unresolvable as _Unresolvable
  File "/home/zezen/.local/lib/python3.12/site-packages/referencing/__init__.py", line 5, in <module>
    from referencing._core import Anchor, Registry, Resource, Specification
  File "/home/zezen/.local/lib/python3.12/site-packages/referencing/_core.py", line 9, in <module>
    from rpds import HashTrieMap, HashTrieSet, List
  File "/home/zezen/.local/lib/python3.12/site-packages/rpds/__init__.py", line 1, in <module>
    from .rpds import *
ModuleNotFoundError: No module named 'rpds.rpds'

solveable as per above:

pip install  -U jsonschema
Defaulting to user installation because normal site-packages is not writeable
Requirement already satisfied: jsonschema in /home/zezen/.local/lib/python3.12/site-packages (4.23.0)
Collecting jsonschema
  Downloading jsonschema-4.26.0-py3-none-any.whl.metadata (7.6 kB)
Requirement already satisfied: attrs>=22.2.0 in /home/zezen/.local/lib/python3.12/site-packages (from jsonschema) (25.4.0)
Requirement already satisfied: jsonschema-specifications>=2023.03.6 in /home/zezen/.local/lib/python3.12/site-packages (from jsonschema) (2024.10.1)
Requirement already satisfied: referencing>=0.28.4 in /home/zezen/.local/lib/python3.12/site-packages (from jsonschema) (0.35.1)
Collecting rpds-py>=0.25.0 (from jsonschema)
  Downloading rpds_py-2026.6.3-cp312-cp312-manylinux_2_17_x86_64.manylinux2014_x86_64.whl.metadata (4.1 kB)
Downloading jsonschema-4.26.0-py3-none-any.whl (90 kB)
Downloading rpds_py-2026.6.3-cp312-cp312-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (366 kB)
Installing collected packages: rpds-py, jsonschema
  Attempting uninstall: rpds-py
    Found existing installation: rpds-py 0.20.0
    Uninstalling rpds-py-0.20.0:
      Successfully uninstalled rpds-py-0.20.0
  Attempting uninstall: jsonschema
    Found existing installation: jsonschema 4.23.0
    Uninstalling jsonschema-4.23.0:
      Successfully uninstalled jsonschema-4.23.0