Skip to content

dbx-patch

Build Documentation

Docs with MkDocs uv linting: ruff ty prek security: bandit Semantic Versions Copier License

Patchception: A library to patch the Databricks patching of Python to enable editable package installs.

Features

  • ✅ Enables editable Python package installs (pip install -e .) in Databricks notebooks
  • ✅ Patches Databricks' custom import system to allow workspace directory imports
  • ✅ Automatic patch application via sitecustomize.py (recommended)
  • ✅ Manual patching via patch_dbx() for immediate use
  • ✅ Debug mode with DBX_PATCH_DEBUG environment variable for troubleshooting

Installation

With pip:

python -m pip install dbx-patch

With uv:

uv add dbx-patch

Quick Start

The simplest way to get started - patches current session AND installs automatic patching:

from dbx_patch import patch_and_install
patch_and_install()
# Patches applied + sitecustomize.py installed
# Python will restart automatically in Databricks!

âš¡ Manual Patching (Current Session Only)

If you only want to patch the current Python session without persistence:

from dbx_patch import patch_dbx
patch_dbx()
# Editable installs now work in this session!

🔧 Automatic Patching (Persistent)

For permanent solution that works across all Python restarts:

# Run ONCE per cluster (e.g., in init script or setup notebook)
from dbx_patch import install_sitecustomize
install_sitecustomize()
# Python will restart automatically in Databricks!
# After restart, patches are applied automatically on every Python startup
  • sys_path_init.py runs during Python interpreter initialization
  • Your notebook code runs after initialization completes
  • By the time you call patch_dbx(), the import system is already configured
  • Editable install paths have already been removed from sys.path
  • Import hooks are already installed and active

The Solution: sitecustomize.py

Python automatically imports sitecustomize.py during interpreter initialization, before any Databricks code runs:

  1. Python interpreter starts
  2. sitecustomize.py runs → ✅ Patches are applied early
  3. Databricks code tries to run → ✅ Already patched!
  4. Your notebook code runs → ✅ Editable installs work!
# ✅ This WORKS - patches applied at startup
from dbx_patch import install_sitecustomize
install_sitecustomize()  # Installs sitecustomize.py + auto-restarts Python

Implementation details:

  • sitecustomize.py patches sys_path_init before it runs
  • Import hooks are modified before they're installed
  • Editable install paths are preserved in sys.path
  • All patches are applied silently during startup

For detailed technical explanation, see Technical Implementation

Docs

uv run mkdocs build -f ./mkdocs.yml -d ./_build/

Update template

copier update --trust -A --vcs-ref=HEAD

Credits

This project was generated with 🚀 python project template.