dbx Ubuntu 22.04 安装 dbx 0.8.19 指南

Ubuntu 22.04 安装 dbx 0.8.19 的完整指南：pip 直装、pipx、离线 wheel 三种方案逐一实测，沉淀缺 git、click 8.2 不兼容、pipx 缺 pkg_resources 三类真实故障排障实录，含版本选型、升级降级与卸载清理。

dbxDatabricks数据平台2026/10/23

dbx Ubuntu 22.04 安装 dbx 0.8.19 指南

目标：在一台 Ubuntu 22.04 服务器上从零安装 dbx 0.8.19（Databricks Labs 出品的 Databricks 作业 CI/CD CLI），跑通 dbx --version、dbx init、dbx configure 等本地验证，并沉淀安装过程中三类真实故障的排障实录。已在 Ubuntu 22.04（x86_64）+ Python 3.10.12 环境逐条实测通过（实测日期 2026-10-23）。

一、环境信息

本文所有命令与回显均在以下环境实测：

项目值
操作系统Ubuntu 22.04（x86_64）
Python3.10.12（系统自带 python3）
pip22.0.2（apt 的 python3-pip 提供）
dbx 目标版本0.8.19（PyPI 最新稳定版，2024-07-02 发布，查询日期 2026-10-23）
关键依赖版本typer 0.7.0、click 8.1.8（需固定，原因见方案 A）、databricks-cli 0.17.8、databricks-sdk 0.156.0、mlflow-skinny 2.22.5、GitPython 3.2.1
网络可访问 pypi.org 与 files.pythonhosted.org（在线方案）；离线方案无需外网

💡 说明：dbx 是纯客户端 Python CLI，安装只在本机完成；部署目标 Databricks 工作区的连接属于使用阶段配置，见《dbx 0.8.19 配置参数详解》。

二、前置条件

安装前需要确认三件事：Python 版本、包管理器、以及 git 可执行文件。其中第三点最容易被忽略——dbx 依赖链中的 GitPython 在导入时会检查 git 可执行文件，没有 git 时所有 dbx 命令都会在启动瞬间报 ImportError（排障实录见方案 A 步骤 3）。

# 1. 确认 Python 版本（dbx 要求 >= 3.8，本文实测 3.10）
python3 --version

实测回显：

Python 3.10.12

# 2. 安装基础包：pip、venv、pipx 与 git（git 为必装项）
sudo apt-get update
sudo apt-get install -y python3-pip python3.10-venv pipx git

实测回显（节选）：

Setting up python3-pip (22.0.2+dfsg-1ubuntu0.7) ...
Setting up python3.10-venv (3.10.12-1ubuntu1.3) ...
Setting up pipx (1.0.0-1) ...
Setting up git (1:2.34.1-1ubuntu1.15) ...

# 3. 逐项验证前置条件
git --version
pip3 --version
pipx --version

实测回显：

git version 2.34.1
pip 22.0.2 from /usr/lib/python3/dist-packages/pip (python 3.10)
1.0.0

⚠️ 注意：如果环境暂不具备 sudo 权限，至少要保证 git 在 PATH 中（用户态编译或静态二进制均可），否则方案 A/B 安装完成后 dbx 无法启动。

三、版本选型说明

dbx 已被官方弃用，版本选型的原则是「锁定 0.8.x 最新版、不再追新」：

版本发布日期（PyPI 实查）说明
0.8.192024-07-02最新稳定版，本文实测对象，推荐
0.8.182023-07-14上一版，本文降级实测可用
0.8.142023-05-110.8.x 中期版本
0.8.02022-11-020.8 大版本起点（引入多环境部署文件等变更）
0.7.62022-10-040.7 末版（旧版部署文件结构，老项目常见）

选型结论：

  1. 新装一律用 0.8.19：它是终结版本，修复到 2024 年 7 月为止；与本文依赖组合（click 8.1.8）组合后可稳定运行。
  2. 不要追旧：0.6/0.7 的部署文件结构与 0.8 不兼容，除非要维护的存量项目本身就停在旧版。
  3. Python 版本：官方要求 Python >= 3.8；本文在 3.10.12 完整验证。3.12+ 未验证，不建议冒险（dbx 停更，无法跟进新解释器兼容性）。

四、安装方案 A：pip 直装（在线）

本方案用系统 pip 直接安装，步骤最少，适合个人开发机快速上手。核心风险点：pip 会给 dbx 配上当下最新的 click（8.5.x），而 dbx 锁定的 typer 0.7.0 与 click >= 8.2 不兼容，必须手工固定 click 8.1.8。

4.1 安装 dbx

sudo pip3 install dbx

实测回显（节选，完整输出约 40 行依赖解析）：

Successfully built databricks-cli
Installing collected packages: text-unidecode, commonmark, zipp, watchdog, urllib3, tzdata, typing_extensions, tenacity, tabulate, sqlparse, smmap, six, shellingham, pyyaml, python-slugify, pygments, pycparser, pyasn1, protobuf, propcache, pathspec, packaging, oauthlib, MarkupSafe, idna, h11, frozenlist, colorama, cloudpickle, click, charset_normalizer, certifi, cachetools, binaryornot, attrs, async-timeout, annotated-doc, aiohappyeyeballs, uvicorn, typer, rich, requests, python-dateutil, pyjwt, pydantic, pyasn1-modules, opentelemetry-api, multidict, jinja2, importlib_metadata, gitdb, exceptiongroup, cffi, aiosignal, yarl, opentelemetry-semantic-conventions, gitpython, databricks-cli, cryptography, arrow, anyio, starlette, opentelemetry-sdk, google-auth, cookiecutter, aiohttp, fastapi, databricks-sdk, mlflow-skinny, dbx
Successfully installed MarkupSafe-3.0.4 ... click-8.5.0 ... databricks-cli-0.17.8 databricks-sdk-0.156.0 dbx-0.8.19 ... mlflow-skinny-2.22.5 ... typer-0.7.0 ...

注意回显中 click-8.5.0——这正是随后故障的根源。

4.2 故障实录一：缺 git 导致命令无法启动

安装完成直接运行任何 dbx 命令（此处以 dbx --version 为例），若系统没有 git 可执行文件：

dbx --version

实测回显（完整错误头）：

Traceback (most recent call last):
  File "/usr/local/lib/python3.10/dist-packages/git/__init__.py", line 296, in <module>
    refresh()
  File "/usr/local/lib/python3.10/dist-packages/git/__init__.py", line 287, in refresh
    if not Git.refresh(path=path):
  File "/usr/local/lib/python3.10/dist-packages/git/cmd.py", line 926, in refresh
    raise ImportError(err)
ImportError: Bad git executable.
The git executable must be specified in one of the following ways:
    - be included in your $PATH
    - be set via $GIT_PYTHON_GIT_EXECUTABLE
    - explicitly set via git.refresh(<full-path-to-git-executable>)

All git commands will error until this is rectified.

This initial message can be silenced or aggravated in the future by setting the
$GIT_PYTHON_REFRESH environment variable. Use one of the following values:
    - quiet|q|silence|s|silent|none|n|0: for no message or exception
    - warn|w|warning|log|l|1: for a warning message (logging level CRITICAL, displayed by default)
    - error|e|exception|raise|r|2: for a raised exception

Example:
    export GIT_PYTHON_REFRESH=quiet

定位与解决：GitPython 在导入时就探测 git 可执行文件；dbx 的 --branch-name、部署资产分支隔离等功能依赖它。安装 git 即修复：

sudo apt-get install -y git
git --version

实测回显：

git version 2.34.1

💡 若确实无法安装 git，可设置 GIT_PYTHON_REFRESH=quiet 让 GitPython 跳过启动检查，但 dbx 涉及分支识别的部署功能会受影响，不推荐。

4.3 故障实录二：click 8.5 与 typer 0.7.0 不兼容

装好 git 后再次运行：

dbx --version

实测回显（报错主体，traceback 中段省略）：

╭───────────────────── Traceback (most recent call last) ──────────────────────╮
│ /usr/local/bin/dbx:5 in <module>                                             │
│   5 from dbx.cli import entrypoint                                           │
│ ...
│ /usr/local/lib/python3.10/dist-packages/dbx/cli.py:223 in <module>           │
│ ❱ 223 click_app = get_click_app()                                            │
│ ...
│ /usr/local/lib/python3.10/dist-packages/click/core.py:3163 in _validate      │
╰──────────────────────────────────────────────────────────────────────────────╯
TypeError: Secondary flag is not valid for non-boolean flag.

定位与解决：dbx 0.8.19 依赖 typer==0.7.0（实测 pip3 show typer 为 0.7.0），而 typer 0.7.0 的参数构造方式在 click 8.2 起的严格校验下抛 TypeError: Secondary flag is not valid for non-boolean flag.。dbx 停更后无人适配，需把 click 降回 8.1.x：

sudo pip3 install 'click==8.1.8'
dbx --version

实测回显：

[dbx][2026-10-23 08:41:19.654] 🧱 Databricks eXtensions aka dbx, version ~> 0.8.19

4.4 验证

dbx --version
dbx --help

实测回显（--help 为节选）：

 Usage: dbx [OPTIONS] COMMAND [ARGS]...

 🧱 Databricks eXtensions aka dbx. Please find the main docs page here.

╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --version                                                                    │
│ --install-completion          Install completion for the current shell.      │
│ --show-completion             Show completion for the current shell, to copy │
│                               it or customize the installation.              │
│ --help                        Show this message and exit.                    │
╰──────────────────────────────────────────────────────────────────────────────╯
╭─ Commands ───────────────────────────────────────────────────────────────────╮
│ configure  🔧 Configures project environment in the current folder.          │
│ deploy     📦 Deploy project to artifact storage.                            │
│ destroy    🚮 Delete defined workflows and relevant assets.                  │
│ execute    🔥 Executes chosen workload on the interactive cluster.           │
│ init       💎 Generates new project from the template.                       │
│ launch     🚀 Launch the workflow on a job cluster.                          │
│ sync       🔄 Sync local files to Databricks and watch for changes.          │
╰──────────────────────────────────────────────────────────────────────────────╯

五、安装方案 B：pipx 安装（推荐）

pipx 为每个工具建独立虚拟环境，不污染系统 Python，是 Python CLI 工具的推荐装法。除 click 之外，新版 pipx 还有一处独立故障：其创建的虚拟环境默认不含 setuptools，而 dbx 启动即 import pkg_resources，需手工注入旧版 setuptools。

5.1 安装

pipx install dbx

实测回显：

creating shared libraries...
upgrading shared libraries...
installing dbx...
⚠️  Note: dbx was already on your PATH at /usr/local/bin/dbx
⚠️  Note: '/root/.local/bin' is not on your PATH environment variable. These
    apps will not be globally accessible until your PATH is updated. Run `pipx
    ensurepath` to automatically add it, or manually modify your PATH in your
    shell's config file (i.e. ~/.bashrc).
done! ✨ 🌟 ✨
  installed package dbx 0.8.19, installed using Python 3.10.12
  These apps are now globally available
    - dbx

5.2 故障实录三：pipx 虚拟环境缺 pkg_resources

/root/.local/bin/dbx --version

实测回显（错误头）：

Traceback (most recent call last):
  File "/root/.local/bin/dbx", line 3, in <module>
    from dbx.cli import entrypoint
  File "/root/.local/pipx/venvs/dbx/lib/python3.10/site-packages/dbx/cli.py", line 6, in <module>
    from dbx.commands.configure import configure
  ...
  File "/root/.local/pipx/venvs/dbx/lib/python3.10/site-packages/dbx/constants.py", line 3, in <module>
    import pkg_resources
ModuleNotFoundError: No module named 'pkg_resources'

定位与解决：dbx 的 constants.py 在模块加载期 import pkg_resources（setuptools 附属包）。新版 setuptools 已按官方计划移除 pkg_resources（其弃用公告标注 removal 最早 2025-11-30），因此向 pipx 虚拟环境注入「最新 setuptools」仍然无效，必须注入 81 之前的版本。dbx 0.8.19 的 pipx 完整修复共两条：

# 1. 注入带 pkg_resources 的旧版 setuptools
pipx runpip dbx install 'setuptools<81'

# 2. 固定 click 8.1.8（与方案 A 同因）
pipx runpip dbx install 'click==8.1.8'

# 3. PATH 持久化（若 ~/.local/bin 不在 PATH 中）
pipx ensurepath

5.3 验证

/root/.local/bin/dbx --version

实测回显：

/root/.local/pipx/venvs/dbx/lib/python3.10/site-packages/dbx/constants.py:3: UserWarning: pkg_resources is deprecated as an API. See https://setuptools.pypa.io/en/latest/pkg_resources.html. The pkg_resources package is slated for removal as early as 2025-11-30. Refrain from using this package or pin to Setuptools<81.
  import pkg_resources
[dbx][2026-10-23 08:41:19.654] 🧱 Databricks eXtensions aka dbx, version ~> 0.8.19

⚠️ 注意：首行 UserWarning 是 setuptools 的弃用提示，可忽略；dbx 功能不受影响。pipx list 应显示 package dbx 0.8.19：

pipx list

实测回显：

venvs are in /root/.local/pipx/venvs
apps are exposed on your $PATH at /root/.local/bin
   package dbx 0.8.19, installed using Python 3.10.12
    - dbx

六、安装方案 C：离线安装（内网隔离场景）

生产内网常无外网出口，可在任一联网机器上用 pip download 把 dbx 及全部依赖打成 wheel 包目录，再拷贝到内网服务器离线安装。click 8.1.8 一并在下载阶段固定，离线包即自洽。

6.1 联网侧：下载离线包

pip3 download dbx 'click==8.1.8' -d ./dbx-offline

实测回显（节选）与产物统计：

Saved ./dbx-offline/dbx-0.8.19-py3-none-any.whl
Saved ./dbx-offline/click-8.1.8-py3-none-any.whl
...

ls ./dbx-offline | wc -l

实测回显：

70

共 70 个 wheel 文件（含 dbx 本体、databricks-cli、mlflow-skinny 等），把整个 dbx-offline 目录拷贝到内网服务器（如 /opt/dbx-offline）。

6.2 内网侧：离线安装到虚拟环境

python3 -m venv /opt/dbx-venv
/opt/dbx-venv/bin/pip install --no-index --find-links /opt/dbx-offline dbx 'click==8.1.8'

实测回显（节选）：

Looking in links: /opt/dbx-offline
...
Successfully installed ... dbx-0.8.19 ...

6.3 验证

/opt/dbx-venv/bin/dbx --version

实测回显：

[dbx][2026-10-23 08:51:12.444] 🧱 Databricks eXtensions aka dbx, version ~> 0.8.19

💡 说明：python3 -m venv 创建的虚拟环境自带 setuptools（含 pkg_resources），因此方案 C 无需方案 B 的 setuptools 注入步骤；click 固定则任何方案都需要。

七、方案对比与选择建议

维度A：pip 直装B：pipx（推荐）C：离线 wheel
隔离性汇入系统/用户 Python，易与其他包冲突独立虚拟环境，互不影响独立虚拟环境
联网要求安装时需外网安装时需外网仅打包机联网，内网服务器零外网
修复步骤装 git + 固定 click 8.1.8装 git + 固定 click + 注入 setuptools<81装 git + 固定 click（venv 自带 setuptools）
升级/多版本pip3 install dbx==<版本>pipx upgrade/pipx install dbx==<版本>重建 wheel 目录 + venv
适用对象个人开发机、临时环境长期使用的开发机（推荐）生产内网、隔离环境

选择建议：开发机优先 B（pipx），内网环境走 C；A 仅在临时验证或与系统 Python 深度绑定的场景使用。三条方案都必须落 click==8.1.8 固定，这是 dbx 0.8.19 在 2026 年安装的共同前提。

八、配置说明

安装只是第一步，dbx 的配置分三层，详细字段见《dbx 0.8.19 配置参数详解》，此处给出装完即用的最小配置：

  1. 认证配置（按优先级）：
# 方式一：环境变量（CI/CD 推荐）
export DATABRICKS_HOST="https://adb-<org-id>.<region-id>.azuredatabricks.net"
export DATABRICKS_TOKEN="dapi<你的访问令牌>"

# 方式二：databricks-cli profile 文件 ~/.databrickscfg（本地开发常用）
cat > ~/.databrickscfg <<'EOF'
[DEFAULT]
host = https://adb-<org-id>.<region-id>.azuredatabricks.net
token = dapi<你的访问令牌>
EOF
chmod 600 ~/.databrickscfg

  1. 项目配置：进入项目目录后由 .dbx/project.json 与 conf/deployment.yml 承担，可用 dbx configure 命令生成或修改。

  2. shell 补全（可选）：

dbx --install-completion

⚠️ 注意：~/.databrickscfg 内含访问令牌，务必 chmod 600，不要提交进代码仓库（dbx init 生成的 .gitignore 已包含 .env 类文件，但不含 databrickscfg）。

九、升级、降级与多版本管理

dbx 停更后不存在「升级」，主要是版本回退与并存管理，以下均实测：

# 降级到指定版本（0.8.18）
sudo pip3 install dbx==0.8.18
dbx --version

实测回显：

[dbx][2026-10-23 08:52:11.172] 🧱 Databricks eXtensions aka dbx, version ~> 0.8.18

# 回到 0.8.19（同时带上 click 固定）
sudo pip3 install dbx==0.8.19 'click==8.1.8'
dbx --version

实测回显：

[dbx][2026-10-23 08:52:14.539] 🧱 Databricks eXtensions aka dbx, version ~> 0.8.19

多版本并存建议用虚拟环境：每个 venv 装一个 dbx 版本（如 /opt/dbx-0.8.18-venv、/opt/dbx-0.8.19-venv），按需激活；pipx 也可 pipx install dbx==0.8.18 后用 pipx list 管理，但同名工具 pipx 默认只保留一个安装实例。

十、常见问题

Q1：运行任何 dbx 命令都报 ImportError: Bad git executable.？ GitPython 导入期检查 git 可执行文件失败。安装 git：sudo apt-get install -y git；确实无法安装时设 export GIT_PYTHON_REFRESH=quiet，但分支识别相关功能会受影响（见 4.2 实录）。

Q2：报 TypeError: Secondary flag is not valid for non-boolean flag.？ click >= 8.2 与 dbx 锁定的 typer 0.7.0 不兼容。固定旧版：pip3 install 'click==8.1.8'（pipx 用 pipx runpip dbx install 'click==8.1.8'）（见 4.3 实录）。

Q3：报 ModuleNotFoundError: No module named 'pkg_resources'？ 运行环境缺 setuptools（或 setuptools 过新已移除 pkg_resources）。venv 内：pip install 'setuptools<81'；pipx 内：pipx runpip dbx install 'setuptools<81'（见 5.2 实录）。

Q4：pipx 装完提示 dbx 不在 PATH？ 执行 pipx ensurepath 并重开 shell，把 ~/.local/bin 加入 PATH（见 5.1 回显中的 pipx 提示）。

Q5：pip 输出 Running pip as the 'root' user ... 警告？ 这是 pip 对 root 直装的常规提醒，不影响功能；介意者改用方案 B/C 的虚拟环境安装。

Q6：dbx deploy 报 No valid authentication information was provided.？ 安装验证已通过，进入使用阶段但未配置凭据。按第八节配置 DATABRICKS_HOST/DATABRICKS_TOKEN 或 ~/.databrickscfg，详见《dbx 0.8.19 配置参数详解》。

Q7：dbx sync 报 Could not find a databricks-cli config for profile DEFAULT？ sync 命令族不走环境变量认证，读取的是 ~/.databrickscfg profile；创建该文件并填入 [DEFAULT] 段即可（见《dbx 0.8.19 常用 CLI 命令详解》sync 一节）。

十一、卸载与清理

按安装方式对应卸载，均实测：

# 卸载 dbx 本体（方案 A）
sudo pip3 uninstall dbx -y

实测回显：

Found existing installation: dbx 0.8.19
Uninstalling dbx-0.8.19:
  Successfully uninstalled dbx-0.8.19

# 方式 B：pipx 卸载（连同虚拟环境）
pipx uninstall dbx

# 方式 C：直接删除虚拟环境与离线包目录
rm -rf /opt/dbx-venv /opt/dbx-offline

# 清理认证文件（如不再使用）
rm -f ~/.databrickscfg

卸载后验证：

which dbx || echo 'dbx 已卸载'

实测回显（venv 场景卸载后）：

bash: /lab/dbx-offline-venv/bin/dbx: No such file or directory

依赖残留（databricks-cli、mlflow-skinny 等）如需一并清理，可 sudo pip3 uninstall databricks-cli databricks-sdk mlflow-skinny -y，或保留不影响其他工具。

十二、参考链接

  1. PyPI 项目页（版本与依赖元数据）：https://pypi.org/project/dbx/
  2. GitHub 仓库（含弃用声明）：https://github.com/databrickslabs/dbx
  3. Databricks 官方文档 dbx 归档章节：https://docs.databricks.com/en/archive/dev-tools/dbx/dbx.html
  4. pipx 官方文档：https://pypa.github.io/pipx/
  5. setuptools pkg_resources 弃用公告：https://setuptools.pypa.io/en/latest/pkg_resources.html

本系列其余篇目：《dbx 介绍与选型指南》《dbx 0.8.19 配置参数详解》《dbx 0.8.19 常用 CLI 命令详解》。