{"id":4596,"library":"jupyter-server-ydoc","title":"jupyter-server-ydoc","description":"jupyter-server-ydoc is a Jupyter Server extension that integrates collaborative shared models into Jupyter environments, enabling real-time co-editing of notebooks and files. It leverages Yjs for document synchronization. The current Python package version is 2.3.0, and it is part of the larger Jupyter Collaboration project, which sees frequent updates and aims for close integration with JupyterLab and Jupyter Server.","status":"active","version":"2.3.0","language":"en","source_language":"en","source_url":"https://github.com/jupyterlab/jupyter-collaboration/tree/main/projects/jupyter-server-ydoc","tags":["jupyter","server-extension","collaboration","realtime","ydoc","jupyterlab"],"install":[{"cmd":"pip install jupyter-server-ydoc","lang":"bash","label":"Install jupyter-server-ydoc"}],"dependencies":[{"reason":"Provides Yjs-based document models for Jupyter content.","package":"jupyter-ydoc","optional":false},{"reason":"Core dependency for Jupyter Server extensions.","package":"jupyterlab-server","optional":false},{"reason":"Handles WebSocket communication for Yjs synchronization.","package":"pycrdt-websocket","optional":false}],"imports":[{"note":"This is the Python class representing the server extension. End-users typically interact with it via `jupyter server extension enable` rather than direct import.","symbol":"YDocExtension","correct":"from jupyter_server_ydoc.extension import YDocExtension"}],"quickstart":{"code":"import subprocess\nimport sys\n\ntry:\n    # Verify that jupyter-server-ydoc is installed\n    import jupyter_server_ydoc\n    print(\"jupyter-server-ydoc is installed.\")\n\n    # Programmatically check if the extension is discoverable by Jupyter Server\n    from jupyter_server.extension.manager import ExtensionManager\n    from jupyter_server.serverapp import ServerApp\n    from traitlets.config import Config\n\n    class DummyServerApp(ServerApp):\n        log_level = 0 # Suppress verbose logging\n        def initialize(self, argv=None):\n            super().initialize(argv)\n            if not hasattr(self, 'config'):\n                self.config = Config()\n\n    app = DummyServerApp()\n    manager = ExtensionManager(serverapp=app)\n    extension_name = \"jupyter_server_ydoc\"\n\n    if extension_name in manager.available_extensions:\n        print(f\"Extension '{extension_name}' is discoverable by Jupyter Server.\")\n        print(\"To enable collaborative features:\")\n        print(f\"1. Run in your terminal: `jupyter server extension enable {extension_name}`\")\n        print(\"2. Start JupyterLab with collaboration enabled: `jupyter lab --collaborative`\")\n        print(\"3. Share the JupyterLab URL with others for real-time collaboration.\")\n    else:\n        print(f\"Error: Extension '{extension_name}' not found by Jupyter Server ExtensionManager.\")\n        print(\"Please ensure `jupyter-server-ydoc` is installed and the environment is correct.\")\n\nexcept ImportError:\n    print(\"Error: jupyter-server-ydoc is not installed.\")\n    print(\"Please install it using: `pip install jupyter-server-ydoc`\")\nexcept Exception as e:\n    print(f\"An unexpected error occurred: {e}\")\n","lang":"python","description":"This quickstart verifies the installation of `jupyter-server-ydoc` and checks if it's discoverable by the Jupyter Server extension manager. It then provides command-line instructions for enabling the extension and starting JupyterLab with collaborative features."},"warnings":[{"fix":"Run `jupyter server extension enable jupyter_server_ydoc` once to persistently enable it. Then launch JupyterLab normally, or with `jupyter lab --collaborative` for explicit collaboration mode.","message":"The extension must be explicitly enabled for Jupyter Server. While `jupyter lab --collaborative` can enable it temporarily, for persistent use or headless servers, use `jupyter server extension enable jupyter_server_ydoc`.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Always check the `requires_dist` section on PyPI or the `pyproject.toml` in the GitHub repository for the exact compatible version ranges of its dependencies. Update all related Jupyter components together if possible.","message":"jupyter-server-ydoc has strict version dependencies on `jupyterlab-server` and `jupyter-ydoc`. Incompatible versions can lead to server startup failures or non-functional collaboration.","severity":"breaking","affected_versions":"All versions"},{"fix":"Verify network settings allow WebSocket traffic on the Jupyter Server port. For Docker, ensure ports are exposed correctly. For cloud deployments, check security groups and load balancer settings.","message":"Collaboration relies on WebSocket communication. Ensure that firewalls, proxies, or Docker container network configurations do not block WebSocket connections to the Jupyter Server.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Upgrade your Python environment to 3.10 or later. Using an older Python version will lead to installation failure.","message":"This library requires Python 3.10 or newer.","severity":"breaking","affected_versions":"<2.3.0 (older versions might support 3.7+), but 2.3.0 explicitly requires >=3.10"}],"env_vars":null,"last_verified":"2026-04-12T00:00:00.000Z","next_check":"2026-07-11T00:00:00.000Z"}