{"record":{"id":"dc15144c41b9ec29","repo":"pola-rs/polars","slug":"no-dynamic-library-found-at-path-path","errorCode":null,"errorMessage":"no dynamic library found at path: {path}","messagePattern":"no dynamic library found at path: (.+?)","errorType":"exception","errorClass":"FileNotFoundError","httpStatus":null,"severity":"error","filePath":"py-polars/src/polars/plugins.py","lineNumber":137,"sourceCode":"    # https://docs.rs/serde-pickle/latest/serde_pickle/\n    return pickle.dumps(kwargs, protocol=5)\n\n\n@lru_cache(maxsize=16)\ndef _resolve_plugin_path(path: Path | str, *, use_abs_path: bool = False) -> Path:\n    \"\"\"Get the file path of the dynamic library file.\"\"\"\n    if not isinstance(path, Path):\n        path = Path(path)\n\n    if path.is_file():\n        return _resolve_file_path(path, use_abs_path=use_abs_path)\n\n    for p in path.iterdir():\n        if _is_dynamic_lib(p):\n            return _resolve_file_path(p, use_abs_path=use_abs_path)\n\n    msg = f\"no dynamic library found at path: {path}\"\n    raise FileNotFoundError(msg)\n\n\ndef _is_dynamic_lib(path: Path) -> bool:\n    return path.is_file() and path.suffix in (\".so\", \".dll\", \".pyd\")\n\n\ndef _resolve_file_path(path: Path, *, use_abs_path: bool = False) -> Path:\n    venv_path = Path(sys.prefix)\n\n    if use_abs_path:\n        return path.resolve()\n    else:\n        try:\n            file_path = path.relative_to(venv_path)\n        except ValueError:  # Fallback\n            file_path = path.resolve()\n\n    return file_path","sourceCodeStart":119,"sourceCodeEnd":155,"githubUrl":"https://github.com/pola-rs/polars/blob/df599052daf96e7a9cc30a3b0c6bd25d6947e3c0/py-polars/src/polars/plugins.py#L119-L155","documentation":"register_plugin_function resolves plugin_path: a file path is used directly; a directory is scanned for a dynamic library (suffix .so, .dll, or .pyd). If none is found, FileNotFoundError is raised. Paths are resolved relative to the active virtualenv (sys.prefix) unless use_abs_path=True.","triggerScenarios":"Passing plugin_path pointing at a directory with no compiled library (e.g. the Python package dir instead of the dir containing the .so); a plugin wheel built for another platform/Python; a source checkout where maturin/cargo build output is elsewhere; venv mismatch making a relative path resolve to the wrong prefix.","commonSituations":"First use of a new polars plugin (e.g. polars_ols, polars_ts); CI or deployment environments where the plugin wheel was not installed for the platform; switching conda/system Python breaks venv-relative resolution.","solutions":["Verify a .so/.dll/.pyd actually exists under the path (ls the directory) and point plugin_path at it or its containing dir","Reinstall the plugin package for your platform/Python (pip install --force-reinstall <plugin>)","Set use_abs_path=True when the path must not be interpreted relative to sys.prefix, or pass the absolute library file path","If building from source, build first (maturin develop / cargo build --release) so the artifact exists"],"exampleFix":"# before\nregister_plugin_function(\n    namespace='mathx', function='logistic', plugin_path='polars-plugin/src',  # no .so there\n)\n\n# after\nregister_plugin_function(\n    namespace='mathx', function='logistic',\n    plugin_path=Path('polars-plugin/target/release').resolve(),  # dir containing libmathx.so\n    use_abs_path=True,\n)","handlingStrategy":"try-catch","validationCode":"from pathlib import Path\np = Path(plugin_path)\nhas_lib = p.is_file() or any(\n    q.suffix in ('.so', '.dll', '.pyd') for q in (p.iterdir() if p.is_dir() else [])\n)\nif not has_lib:\n    raise FileNotFoundError(f'no dynamic library under {p}; build/install the plugin first')","typeGuard":null,"tryCatchPattern":"from polars.plugins import register_plugin_function\ntry:\n    fn = register_plugin_function(namespace='mathx', function='logistic', plugin_path=lib_dir)\nexcept FileNotFoundError as exc:\n    raise RuntimeError(\n        f'polars plugin not built/installed at {lib_dir!r}; run maturin develop'\n    ) from exc","preventionTips":["Confirm the compiled artifact exists in the target directory before registering plugins","Pass absolute paths (or use_abs_path=True) when the venv prefix is not the reference frame","Install plugin wheels matching your OS/Python; source dirs alone are not enough"],"tags":["polars","plugins","native-library","environment"],"backgroundTag":null,"analyzedSha":"df599052daf96e7a9cc30a3b0c6bd25d6947e3c0","analyzedAt":"2026-08-16T12:10:03.978Z","schemaVersion":2},"datasetVersion":"2026-08-16T13:17:31.715Z"}