{"id":4595,"library":"jupyter-server-fileid","title":"Jupyter Server File ID","description":"Jupyter Server File ID is an extension for Jupyter Server that provides an implementation of the File ID service. Its primary purpose is to allow developers to consistently track the path of files within a running Jupyter Server environment over their lifetime, even if the files are moved or renamed. The current version is 0.9.3, with updates released periodically to maintain compatibility and add features.","status":"active","version":"0.9.3","language":"en","source_language":"en","source_url":"https://github.com/jupyter-server/jupyter_server_fileid","tags":["jupyter","jupyter-server","extension","file-management","file-id"],"install":[{"cmd":"pip install jupyter_server_fileid","lang":"bash","label":"Install stable release"}],"dependencies":[{"reason":"This is a Jupyter Server extension and requires a running Jupyter Server instance to function.","package":"jupyter-server","optional":false}],"imports":[{"note":"For typical usage as a Jupyter Server extension, the LocalFileIdManager instance is retrieved from the running ServerApp's settings, not directly imported. Direct import is for advanced scenarios or type hinting.","symbol":"LocalFileIdManager","correct":"from jupyter_server.base.handlers import JupyterHandler\n# LocalFileIdManager is typically accessed via serverapp.settings['file_id_manager']\n# Direct import for type hinting or advanced use might be: from jupyter_server_fileid.manager import LocalFileIdManager"}],"quickstart":{"code":"import os\nimport tempfile\nfrom unittest.mock import MagicMock\n\n# Simulate a minimal ServerApp and its settings for demonstration\nclass MockServerApp:\n    def __init__(self):\n        self.settings = {}\n\n# In a real Jupyter Server environment, serverapp would be the active application instance\nserverapp = MockServerApp()\n\n# --- In a real Jupyter Server, jupyter_server_fileid would populate this setting ---\n# For this quickstart, we'll manually set up a mock manager\n# In a live environment, you would ensure the extension is enabled.\n# Example: serverapp.settings[\"file_id_manager\"] = LocalFileIdManager(parent=serverapp)\n\n# Mocking LocalFileIdManager for a runnable quickstart without a full Jupyter Server setup\nclass MockLocalFileIdManager:\n    def __init__(self):\n        self._files = {}\n        self._next_id = 1\n\n    def index(self, path):\n        abs_path = os.path.abspath(path)\n        for fid, stored_path in self._files.items():\n            if stored_path == abs_path:\n                return fid\n        new_id = str(self._next_id)\n        self._files[new_id] = abs_path\n        self._next_id += 1\n        return new_id\n\n    def get_path(self, file_id):\n        return self._files.get(file_id)\n\n    def update_path(self, file_id, new_path):\n        if file_id in self._files:\n            self._files[file_id] = os.path.abspath(new_path)\n            return True\n        return False\n\nserverapp.settings['file_id_manager'] = MockLocalFileIdManager()\n# ----------------------------------------------------------------------------------\n\n# Access the File ID manager from the server settings\nfim = serverapp.settings['file_id_manager']\n\n# Create a temporary file to demonstrate tracking\nwith tempfile.TemporaryDirectory() as tmpdir:\n    original_path = os.path.join(tmpdir, 'my_notebook.ipynb')\n    with open(original_path, 'w') as f:\n        f.write('# My Notebook')\n\n    # 1. Index the file to get a unique File ID\n    file_id = fim.index(original_path)\n    print(f\"Original path: {original_path}\")\n    print(f\"Generated File ID: {file_id}\")\n\n    # 2. Get the current path using the File ID\n    current_path = fim.get_path(file_id)\n    print(f\"Current path retrieved by ID: {current_path}\")\n\n    # 3. Simulate moving the file\n    new_path = os.path.join(tmpdir, 'moved_notebook.ipynb')\n    os.rename(original_path, new_path)\n    print(f\"File moved to: {new_path}\")\n\n    # In a real scenario, the File ID service would detect and update its internal mapping.\n    # For this mock, we'll manually update for demonstration purposes if `update_path` existed.\n    # A real LocalFileIdManager would likely have filesystem watchers or hooks.\n    fim.update_path(file_id, new_path) # Simulating the internal update\n\n    # 4. Get the path again after the move - it should reflect the new location\n    updated_path = fim.get_path(file_id)\n    print(f\"Updated path retrieved by ID: {updated_path}\")\n\n    assert updated_path == os.path.abspath(new_path)\n    print(\"File ID successfully tracked the moved file.\")\n","lang":"python","description":"This quickstart demonstrates how to obtain and use the `LocalFileIdManager` instance within a simulated Jupyter Server environment. In a real setup, the `serverapp.settings['file_id_manager']` would be automatically populated when the `jupyter_server_fileid` extension is enabled. The example shows how to index a file to get a unique ID, and then resolve that ID back to its current path, even after the file has been moved."},"warnings":[{"fix":"Run `jupyter server extension list` in your terminal to check if `jupyter_server_fileid` is enabled. If not, enable it using `jupyter server extension enable jupyter_server_fileid` (though typically `pip install` enables it automatically).","message":"The `jupyter-server-fileid` extension must be properly enabled within your Jupyter Server. If the frontend components of a Jupyter extension are visible but not functional, always verify the server extension status.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Review the Jupyter Server documentation on configuration. Server-specific traits should be configured in `jupyter_server_config.py` (or JSON equivalent) and refer to `ServerApp` settings, not `NotebookApp`.","message":"Users migrating from older Jupyter Notebook server configurations (`jupyter_notebook_config.py`) to the newer Jupyter Server architecture (`jupyter_server_config.py`) may encounter issues. Ensure that server-specific configurations for extensions like `jupyter-server-fileid` are placed in the correct `jupyter_server_config.py` file.","severity":"gotcha","affected_versions":"Versions of Jupyter Server 1.0.0 and later."},{"fix":"Always interact with `jupyter-server-fileid` by retrieving the `LocalFileIdManager` instance from the `serverapp.settings` dictionary within your Jupyter Server extension or application code. Avoid direct instantiation unless you fully understand its internal dependencies and lifecycle.","message":"The `LocalFileIdManager` instance is typically accessed through `serverapp.settings['file_id_manager']` from the `ServerApp` instance, which is available within the context of a running Jupyter Server. Attempting to directly import and instantiate `LocalFileIdManager` outside of this context may lead to incorrect behavior or require extensive manual setup of its dependencies.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-12T00:00:00.000Z","next_check":"2026-07-11T00:00:00.000Z"}