{"id":4366,"library":"jupyter-ydoc","title":"Jupyter Y-document","description":"jupyter-ydoc provides document structures for collaborative editing in Jupyter environments, leveraging the Ypy library. It enables real-time synchronization of Jupyter notebooks and other file types using Yjs CRDTs. The library is actively maintained by the Jupyter project, with frequent patch and minor releases.","status":"active","version":"3.4.0","language":"en","source_language":"en","source_url":"https://github.com/jupyter-server/jupyter_ydoc","tags":["jupyter","collaboration","real-time","ypy","yjs","crdt","notebooks"],"install":[{"cmd":"pip install jupyter-ydoc","lang":"bash","label":"Install stable version"}],"dependencies":[{"reason":"Core dependency for Yjs CRDT implementation.","package":"ypy","optional":false},{"reason":"Used for converting between Y-document structures and standard Jupyter notebook formats.","package":"notebook_format","optional":false}],"imports":[{"symbol":"YDoc","correct":"from jupyter_ydoc import YDoc"},{"symbol":"YFile","correct":"from jupyter_ydoc import YFile"},{"symbol":"YNotebook","correct":"from jupyter_ydoc import YNotebook"}],"quickstart":{"code":"import json\nfrom jupyter_ydoc import YDoc, YNotebook\n\n# 1. Initialize a YDoc (the core Yjs document)\nydoc = YDoc()\n\n# 2. Create a YNotebook wrapper for the YDoc\n# This initializes the YDoc with an empty notebook structure if it's new.\nynotebook = YNotebook(ydoc)\n\n# 3. Set content from a standard Jupyter notebook dictionary\nnotebook_content = {\n    \"cells\": [\n        {\"cell_type\": \"code\", \"source\": \"print('Hello from jupyter-ydoc!')\", \"metadata\": {}},\n        {\"cell_type\": \"markdown\", \"source\": \"## Getting Started\", \"metadata\": {}}\n    ],\n    \"metadata\": {\n        \"kernelspec\": {\"display_name\": \"Python 3\", \"language\": \"python\", \"name\": \"python3\"},\n        \"language_info\": {\"codemirror_mode\": {\"name\": \"ipython\", \"version\": 3}}\n    },\n    \"nbformat\": 4,\n    \"nbformat_minor\": 5\n}\nynotebook.set(notebook_content)\nprint(\"Notebook content set successfully.\")\n\n# 4. Retrieve content as a standard Jupyter notebook dictionary\nretrieved_content = ynotebook.get()\nprint(\"\\nRetrieved notebook content:\")\nprint(json.dumps(retrieved_content, indent=2))\n\n# 5. Manipulate the notebook content (e.g., add a new cell)\nynotebook.append_cell({\"cell_type\": \"code\", \"source\": \"x = 10\\ny = 20\\nx + y\", \"metadata\": {}})\nprint(\"\\nAdded a new code cell.\")\n\n# 6. Get the updated content\nupdated_content = ynotebook.get()\nprint(\"\\nUpdated notebook content after adding cell:\")\nprint(json.dumps(updated_content, indent=2))\n","lang":"python","description":"This quickstart demonstrates how to initialize a YDoc, wrap it with YNotebook, set content from a standard Jupyter notebook dictionary, retrieve the content, and programmatically add a new cell to the Y-document structure."},"warnings":[{"fix":"Upgrade your Python environment to 3.10 or later.","message":"Starting with version 3.3.0, `jupyter-ydoc` requires Python 3.10 or newer. Installations on older Python versions will fail.","severity":"breaking","affected_versions":">=3.3.0"},{"fix":"Upgrade to `jupyter-ydoc` version 3.3.3 or higher to ensure correct handling of all Unicode characters.","message":"Older versions of `jupyter-ydoc` (prior to 3.3.3) had issues handling multi-byte Unicode characters in files, potentially leading to data corruption or incorrect display.","severity":"gotcha","affected_versions":"<3.3.3"},{"fix":"It is highly recommended to upgrade to `jupyter-ydoc` version 3.3.4 or later to benefit from critical bug fixes related to document synchronization and integrity.","message":"Several bugs in versions prior to 3.3.4 could lead to cell duplication, incorrect reloading, or inconsistent states during collaborative editing of notebooks.","severity":"gotcha","affected_versions":"<3.3.4"},{"fix":"Consult the official documentation for `jupyter-ydoc` version 3.4.0 to understand the new `async_get` and `async_set` methods and their usage in asynchronous contexts.","message":"Version 3.4.0 introduced asynchronous `get` and `set` methods for documents. While existing synchronous methods remain, developers building new integrations or optimizing performance might need to adapt to the new async patterns.","severity":"gotcha","affected_versions":">=3.4.0"}],"env_vars":null,"last_verified":"2026-04-12T00:00:00.000Z","next_check":"2026-07-11T00:00:00.000Z"}