dbx-patch

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

🚀 Recommended: One-Command Setup

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