darktable-org/darktable

# [](https://www.darktable.org/) darktable [](https://github.com/darktable-org/darktable/actions/workflows/ci.yml?query=branch%3Amaster+is%3Acompleted+event%3Apush) [](https://bestpractices.coreinfrastructure.org/projects/470) darktable 是一个开源的摄影工作流应用程序和非破坏性的 raw 显影软件——摄影师的虚拟光台 (lighttable) 和暗房 (darkroom)。它通过数据库管理您的数字底片，允许您通过可缩放的光台进行查看，并使您能够显影 raw 图像、增强它们以及将其导出到本地或远程存储中。  darktable **并非** Adobe® Lightroom® 的免费替代品。 [https://www.darktable.org/](https://www.darktable.org/ "darktable homepage") ## 目录 1. [文档](#documentation) 2. [网站](#website) 3. [系统要求](#requirements) - [支持的平台](#supported-platforms) - [硬件](#hardware) - [AI 功能（可选）](#ai-features-optional ) 4. [安装](#installing) - [最新发布版本](#latest-release) - [开发快照版](#development-snapshot) 5. [从旧版本更新](#updating-from-older-versions) 6. [获取扩展](#obtaining-extensions) 7. [构建](#building) - [依赖项](#dependencies) - [获取源码](#get-the-source) - [获取子模块](#get-submodules) - [编译](#compile) - [延伸阅读](#further-reading) 8. [使用](#using) - [测试/不稳定版本](#testunstable-version) - [常规/稳定版本](#regularstable-version) 9. [贡献](#contributing) 10. [常见问题](#faq) - [为什么我的相机在插入时没有被检测到？](#why-is-my-camera-not-detected-when-plugged-in-) - [为什么在暗房中我的镜头没有被检测到/校正？](#why-is-my-lens-not-detectedcorrected-in-darkroom-) - [为什么光台视图中的缩略图看起来与暗房视图中的预览不同？](#why-do-the-thumbnails-in-the-lighttable-view-look-different-to-the-preview-in-the-darkroom-view-) 11. [Wiki](#wiki) 12. [社区](#community) ## 文档 darktable 用户手册维护在 [dtdocs](https://github.com/darktable-org/dtdocs) 仓库中。 Lua API 文档维护在 [luadocs](https://github.com/darktable-org/luadocs) 仓库中。 ## 网站 网站（[https://www.darktable.org/](https://www.darktable.org/)）维护在 [dtorg](https://github.com/darktable-org/dtorg) 仓库中。 ## 系统要求 ### 支持的平台 * Linux * FreeBSD * NetBSD * OpenBSD * Windows 10 及更高版本 * 运行 macOS 14 及更高版本的 Apple Silicon Mac * 运行 macOS 15 及更高版本的 Intel Mac *不支持大端序平台。* *32 位平台未受官方支持——它们可能可以运行，也可能无法运行。* *darktable 及其使用的库均是在 Linux 平台上开发的。 因此，其他平台可能存在 Linux 版本中没有的额外 bug。 此外，例如在 Windows 平台上，目前尚未实现打印支持。 因此我们建议，如果您可以选择平台的话，请在 Linux 上使用 darktable。* ### 硬件 （最低可用配置 / **推荐最低配置**）： * RAM: 4 GB / **8 GB** * CPU: Intel Pentium 4（Windows 上需 Core 2）/ **Intel Core i5 4×2.4 GHz** * GPU: 无 / **Nvidia，具备 1024 个 CUDA 核心，4 GB 显存，兼容 OpenCL 1.2** * 可用磁盘空间: 250 MB / **1 GB** *darktable 可以在轻量级配置上运行（甚至在 Raspberry Pi 上），但预计诸如 denoise（降噪）、local contrast（局部对比度）、contrast equalizer（对比度均衡器）、retouch（修饰）或 liquify（液化）等模块会慢到难以使用的程度。* *不是必须要有 GPU，但强烈推荐使用 GPU 以获得更流畅的体验。 出于稳妥起见，推荐使用 Nvidia GPU，因为某些 AMD 驱动程序在处理某些模块（如 local contrast）时表现不可靠。* ### AI 功能（可选） Darktable 包含可选的 AI 驱动功能，例如对象掩码、降噪 (denoise) 和放大。 这些功能要求在构建时使用 `-DUSE_AI=ON`（默认关闭），或者在使用构建辅助脚本 `build.sh` 时使用 `--enable-ai`。AI 功能在偏好设置中默认被禁用，必须由用户手动开启。模型可从偏好设置中的 AI 标签页下载 （默认仓库：[darktable-org/darktable-ai](https://github.com/darktable-org/darktable-ai)）。 **CPU 推理** 已内置，开箱即用——无需额外软件。 在 macOS（Apple Silicon）上，CoreML 加速以及在 Windows 上的 DirectML GPU 加速 也已默认内置。在 CPU 上处理比 GPU 慢，但不需要特殊硬件。 **GPU 加速** 能显著加快 AI 推理速度，但需要单独安装启用了 GPU 的 [ONNX Runtime](https://onnxruntime.ai/) 构建： * **NVIDIA (CUDA)：** Linux 和 Windows。 * 支持的 NVIDIA GPU 且驱动程序为最新版本（Maxwell 架构或更新） * [CUDA Toolkit 12](https://developer.nvidia.com/cuda-12-0-0-download-archive) 或 [CUDA Toolkit 13](https://developer.nvidia.com/cuda-13-0-0-download-archive) * [cuDNN 9.x](https://developer.nvidia.com/cudnn-downloads) * **AMD (ROCm)：** 仅限 Linux。 * 支持的 AMD GPU 且驱动程序为最新版本（RDNA2/CDNA 架构或更新），请参阅[兼容性矩阵](https://rocm.docs.amd.com/en/latest/compatibility/compatibility-matrix.html) * [ROCm 6+](https://rocm.docs.amd.com/projects/install-on-linux/en/latest/) * [MIGraphX](https://rocm.docs.amd.com/projects/AMDMIGraphX/en/latest/install/install-migraphx.html)（可能需要单独安装，例如在 Ubuntu 上执行 `apt install migraphx migraphx-dev`） * **Intel (OpenVINO)：** Linux 和 Windows。 * 支持的 Intel GPU 且驱动程序为最新版本（集成显卡 Gen9+、独立显卡 Arc，或 NPU Meteor Lake+） * [Intel OpenCL](https://www.intel.com/content/www/us/en/developer/articles/tool/opencl-drivers.html) 或/和 [Level Zero runtime](https://www.intel.com/content/www/us/en/docs/dpcpp-cpp-compiler/developer-guide-reference/2025-2/intel-oneapi-level-zero.html)（Windows 上随驱动程序提供；在 Linux 上可能需要安装 `intel-opencl-icd` 或 `level-zero`） * 在 Windows 上，需要安装 [OpenVINO Toolkit](https://docs.openvino.ai/2026/get-started/install-openvino/install-openvino-windows.html) * **Windows (DirectML)：** 已内置，适用于任何兼容 DirectX 12 的 GPU（NVIDIA、AMD、Intel）。 无需额外安装。 * Windows 10 1903+（DirectML 是系统组件） * **macOS (CoreML)：** 已内置，自动使用 Apple Neural Engine。 无需额外安装。 * macOS 11+ (Big Sur) * Apple Silicon (M1+) **GPU 显存：** 至少需要 4 GB VRAM。如果 GPU 推理失败（内存不足、不支持的操作、 EP 崩溃），darktable 会自动重试在 CPU 上运行并继续处理。 **AMD 首次运行延迟：** 在 AMD GPU 上，每个模型第一次推理的速度会明显 较慢，因为 ROCm/MIGraphX 会即时编译模型计算图。编译后的计算图 会被缓存，因此随后运行相同模型时速度会很快。 要启用 GPU 加速，请运行以下安装脚本之一： Linux: ``` curl -fsSL https://raw.githubusercontent.com/darktable-org/darktable/HEAD/tools/ai/install-ort-gpu.sh | bash ``` Windows (PowerShell): ``` irm https://raw.githubusercontent.com/darktable-org/darktable/HEAD/tools/ai/install-ort-gpu.ps1 | iex ``` 然后，在偏好设置中通过 **AI** 标签页将 darktable 指向已安装的库 （点击 **检测**）。有关标志、先决条件、手动安装和故障排除的信息，请参阅 [tools/ai/README.md](tools/ai/README.md)。使用 `darktable -d ai` 验证当前活动的提供程序。 ## 安装 如果最新的发布版本仍未提供适用于您所用发行版的预编译包， 您可以按照[下方](#building)的说明自行编译该软件。 ### 最新发布版本 5.4.1 (稳定版) * [下载 Windows 安装包](https://github.com/darktable-org/darktable/releases/download/release-5.4.1/darktable-5.4.1-win64.exe) * [下载 Apple Silicon 版 macOS 磁盘映像](https://github.com/darktable-org/darktable/releases/download/release-5.4.1/darktable-5.4.1-arm64.dmg) * [下载 Intel 版 macOS 磁盘映像](https://github.com/darktable-org/darktable/releases/download/release-5.4.1/darktable-5.4.1-x86_64.dmg) * [下载 Linux AppImage](https://github.com/darktable-org/darktable/releases/download/release-5.4.1/Darktable-5.4.1-x86_64.AppImage) * [为 Linux 发行版安装原生软件包或添加第三方仓库](https://software.opensuse.org/download.html?project=graphics:darktable:stable&package=darktable) * [为 Linux 安装 Flatpak 软件包](https://flathub.org/apps/details/org.darktable.Darktable) * [关于在任何系统上安装 darktable 的更多信息](https://www.darktable.org/install/) *使用预编译包时，请确保其构建时包含了对 Lua、OpenCL、OpenMP 和 Colord 的支持。 这些是可选项，如果缺少它们，也不会阻止 darktable 运行， 但缺少这些组件会降低用户体验。 您可以通过使用 `--version` 命令行选项运行 darktable 来检查它们。* ### 开发快照版 开发快照反映了 master 分支的当前状态。它旨在用于测试，通常并不稳定。有关使用 master 分支的警告和注意事项，请参阅[下文](#get-the-source)。 * [直接为某些 Linux 发行版安装原生软件包或添加第三方仓库](https://software.opensuse.org/download.html?project=graphics:darktable:master&package=darktable)（每天提供一个快照） * [ nightly 版本二进制包适用于 Linux (AppImage)、macOS 和 Windows](https://github.com/darktable-org/darktable/releases/tag/nightly) ## 从旧版本更新 从较旧的发布版本更新 darktable 时，您只需安装 最新版本。现有文件将被保留。 但是，较新的版本偶尔需要更改图库数据库的结构 （该数据库包含 darktable 已知的全部图像列表及其编辑历史记录）。如果发生这种情况， 系统将提示您升级数据库或关闭软件。 **迁移到较新的数据库结构/较新版本意味着您的编辑（无论新旧）将不再兼容旧版本的 darktable。** 升级是最终性的。 新版本始终兼容旧的编辑内容，但较新的编辑内容通常不兼容旧版本。 当新版本导致数据库升级时，darktable 会自动备份图库数据库 （例如备份在 `~/.config/darktable/library.db-pre-3.0.0` 中），因此 如有需要，您可以通过还原此备份来回退到以前的版本 （只需将其重命名为 `library.db`）。 您将无法使用仅支持旧版本数据库的 darktable 版本打开更新版本的数据库。 这是不可能实现的，因为旧版本的应用程序不知道数据库 schema 发生了什么变化，因此其代码无法与其协同工作。 如果 XMP sidecar 文件包含较新版本的处理模块或新模块，您将能够导入带有该文件的图像，但这些图像的编辑部分将被丢弃并丢失。 如果您计划经常在两个版本（新/不稳定版和旧/稳定版）之间切换，请参阅[下文](#testunstable-version)了解如何安全执行此操作的详细信息。 ## 获取扩展 扩展和插件使用 Lua 脚本语言，可在[此处](https://github.com/darktable-org/lua-scripts)下载。Lua 支持在 darktable 中是可选的，因此在编译时请确保您的系统上已安装了 `lua` 解释器及其开发文件（软件包 `lua-dev` 或 `lua-devel`，具体取决于您的发行版），或者确保您正在使用的预编译包已包含此库。 扩展允许导出到各种媒体和网站，合并/堆栈/混合 HDR、全景图或焦点包围，应用基于 AI 的面部识别，管理标签和 GPS 数据等。 ## 构建 ### 依赖项 兼容的编译器/工具链： * Clang: 15 及更高版本 * GCC: 12 及更高版本 * MinGW-w64: 10 及更高版本 * XCode: 15.2 及更高版本 必需依赖项（最低版本）： * CMake 3.18 * GTK 3.24.15 * GLib 2.56 * SQLite 3.26 * libcurl 7.56 * libpng 1.5.0 *(用于 PNG 导入和导出，以及读取 PNG 格式的 LUT 文件)* * Exiv2 0.27.2 *(但对于 Canon CR3 raw 导入，需要至少使用启用了 ISO BMFF 支持构建的 0.27.4 版本)* * potrace 1.16 * pugixml 1.8 必需依赖项（无版本要求）： * Lensfun *(用于自动镜头校正)*（注意：不支持 alpha 0.3.95 及 git master 分支） * lib *(原始的 IJG 库及 API 兼容的替代品（如 libjpeg-turbo）均可正常工作)* * LibTIFF *(用于 TIFF 导入和导出)* * Little CMS 2 可选依赖项（最低版本）： * OpenMP 4.5 *(用于 CPU 多线程和 SIMD 矢量化)* * LLVM 7 *(用于编译时进行 OpenCL 检查)* * OpenCL 1.2 *(用于 GPU 加速计算)* * Lua 5.4 *(用于插件和扩展脚本)* * G'MIC 2.7.0 *(用于支持 .gmz 压缩 LUT 文件)* * libgphoto2 2.5 *(用于相机联机)* * Imath 3.1.0 *(用于 16 位“半精度”浮点 TIFF 导出和更快的导入)* * libavif 0.9.3 *(用于 AVIF 导入和导出)* * ONNX Runtime 1.18 *(用于 AI 推理)* * libarchive 3.8.5 *(用于下载 AI 模型)* * libheif 1.13.0 *(用于 HEIF 导入和导出；如果没有 libavif，也可用于 AVIF 导入)* * libjxl 0.7.0 *(用于 JPEG XL 导入和导出)* * WebP 0.3.0 *(用于 WebP 导入和导出)* 可选依赖项（无版本要求）： * colord, Xatom *(用于获取系统显示器的色彩配置文件)* * PortMidi *(用于支持 MIDI 输入)* * SDL2 *(用于支持游戏手柄输入)* * CUPS *(用于支持打印模式)* * OpenEXR *(用于 EXR 导入和导出)* * OpenJPEG *(用于 JPEG 2000 导入和导出)* * GraphicsMagick 或 ImageMagick *(用于杂项图像格式导入)* 要在 Linux 系统上安装所有依赖项，您可以使用您所用发行版的源仓库。 这将安装与在您的系统上编译官方 darktable 软件包所使用的相同软件包。 最可能的情况是，您希望编译一个比发行版中打包的版本更新的版本。因此请 注意，虽然这种情况不常发生，但 darktable 的新版本可能会 包含新的（必需或可选）依赖项。因此，以下命令仅简化了您的 构建环境的创建，但不能代替您对构建过程的关注，并且可能需要您寻找并 安装某些特定的额外依赖包。 #### Fedora 和 RHEL/CentOS ``` sudo dnf builddep darktable ``` #### OpenSuse ``` sudo zypper si -d darktable ``` #### Ubuntu 近期的 Ubuntu 版本默认不再包含 deb-src 源，甚至连被注释掉的格式也没有。 要添加它们，您需要运行“软件和更新”，并在打开的第一个标签页“Ubuntu 软件”中， 勾选“源代码”复选框。只有在此之后，您才能使用以下命令： ``` sudo apt-get build-dep darktable ``` #### Debian ``` sudo apt-get build-dep darktable ``` ### 获取源码 #### Master 分支（不稳定） master 分支包含最新版本的源代码，其旨在用于： * 作为开发者的工作基础， * 供 beta 测试人员寻找 bug， * 供那些愿意为了新功能而牺牲稳定性、不想等待下一个发布版本的用户使用。 master 分支不提供任何稳定性保证，可能会损坏您的数据库和 XMP 文件， 导致数据丢失、编辑历史记录丢失，或暂时破坏与以前版本和提交的兼容性。 它有多危险？大多数时候，它是相当稳定的。与任何滚动发布的部署一样，bug 出现的频率更高， 但修复得也更快。不过有时，这些 bug 可能会导致图片编辑历史记录的丢失或不一致。 如果您将来不需要再次打开您的编辑，这没问题；但如果您管理着大量资产，可能就不太合适了。 在备份了您的 `~/.config/darktable` 目录以及您打算使用 master 分支打开的任何图片的 sidecar .XMP 文件之后，您可以按如下方式获取源码： ``` git clone --recurse-submodules --depth 1 https://github.com/darktable-org/darktable.git cd darktable ``` 请参阅下文（“使用”部分），了解如何在不损坏您常规稳定版安装和文件的情况下，启动不稳定版本的测试安装。 #### 最新稳定版 5.4.1 darktable 项目每年在夏至和冬至时发布两个主要版本，使用偶数进行标记（例如 4.2、4.4、4.6、4.8）。 次要修订版本使用第三位数字进行标记（例如 4.4.1、4.4.2），主要提供错误修复和相机支持。 您可能希望自行编译这些稳定版本，以便在您的特定计算机上获得更好的性能： ``` git clone --recurse-submodules --depth 1 https://github.com/darktable-org/darktable.git cd darktable git fetch --tags git checkout tags/release-5.4.1 ``` ### 获取子模块 请注意，[libxcf](https://github.com/houz/libxcf.git)、[OpenCL](https://github.com/KhronosGroup/OpenCL-Headers.git)、[RawSpeed](https://github.com/darktable-org/rawspeed)、[whereami](https://github.com/gpakosz/whereami) 和 [LibRaw](https://github.com/LibRaw/LibRaw) 是通过 git 子模块进行跟踪的，因此在检出 darktable 之后，您还需要更新/检出这些子模块： ``` git submodule update --init ``` ### 编译 #### 简单方式 警告：如果您之前编译过 darktable，请不要忘记首先彻底删除（`rm -R`）`build` 和 `/opt/darktable` 目录，以避免不同版本的文件发生冲突。许多被报告的奇怪行为和 瞬时 bug 都可以追溯到构建缓存未正确使已更改的依赖项失效，因此 最安全的方法是完全删除以前编译的二进制文件并从头开始。 darktable 提供了一个 shell 脚本，可以在 Linux 和 macOS 上通过单条命令自动处理常规情况下的构建。 ``` ./build.sh --prefix /opt/darktable --build-type Release --install --sudo ``` 如果您想在常规/稳定版本旁边安装一个测试版本，请更改安装前缀： ``` ./build.sh --prefix /opt/darktable-test --build-type Release --install --sudo ``` 这会仅针对您的系统架构编译软件，包含： * `-O3` 优化级别， * 如果检测到，则支持 SSE/AVX， * 如果检测到，则支持 OpenMP（多线程和矢量化）， * 如果检测到，则支持 OpenCL（GPU 卸载）， * 如果检测到，则支持 Lua 脚本。 如果您想让 darktable 与其他应用程序一起显示，只需添加一个符号链接： ``` ln -s /opt/darktable/share/applications/org.darktable.darktable.desktop /usr/share/applications/org.darktable.darktable.desktop ``` 现在，您自行编译的 darktable 就可以像任何预打包的软件一样使用了。 #### 手动方式 或者，您可以使用手动构建来传递自定义参数。 ##### Linux ``` mkdir build cd build cmake -DCMAKE_INSTALL_PREFIX=/opt/darktable/ .. cmake --build . sudo cmake --install . ``` ##### macOS 请参阅 [Homebrew](packaging/macosx/BUILD_hb.txt) 或 [MacPorts](packaging/macosx/BUILD.txt) 说明。 ##### Windows 请参阅[这些说明](packaging/windows/README.md)。 ### 使用 #### 测试/不稳定版本 要使用 darktable 的测试版本而不损坏您常规/稳定版本的文件和数据库，请在终端中使用以下命令启动 darktable： ``` /opt/darktable-test/bin/darktable --configdir "~/.config/darktable-test" ``` 并确保在“偏好设置” -> “存储” -> “XMP sidecar 文件”中，将“创建 XMP 文件”选项设置为“从不”。这样， 您的常规/稳定版本将像往常一样将其配置文件保存在 `~/.config/darktable` 中， 测试/不稳定版本将保存在 `~/.config/darktable-test` 中，这两个版本不会产生数据库冲突。 #### 常规/稳定版本 只需从您的桌面应用程序菜单启动它，或者在终端中运行 `darktable` 或 `/opt/darktable/bin/darktable`。如果安装时未在您的应用程序菜单中创建启动器，请运行： ``` sudo ln -s /opt/darktable/share/applications/org.darktable.darktable.desktop /usr/share/applications/org.darktable.darktable.desktop ``` 您可以在 `~/.config/darktable` 中找到 darktable 配置文件。 如果您在启动时遇到崩溃，请尝试在终端中运行 darktable 并使用 `darktable --disable-opencl` 命令禁用 OpenCL。 ### 延伸阅读 这里有一份详尽的构建说明列表，适用于 [Ubuntu/Debian 相关发行版](https://github.com/darktable-org/darktable/wiki/Build-instructions-for-Ubuntu) 或 [Fedora 及相关发行版](https://github.com/darktable-org/darktable/wiki/Build-Instructions-for-Fedora)。这些构建说明很容易适配到许多其他 Linux 发行版上。 ## 贡献 您可以通过多种方式为 darktable 项目做出贡献： * 撰写关于 darktable 的博客 * 为 darktable 创建教程 * 帮助扩充[用户 Wiki](https://github.com/darktable-org/darktable/wiki) 或[用户手册](https://github.com/darktable-org/dtdocs) * 在[用户 Matrix 聊天室](https://matrix.to/#/#darktable-user:matrix.org)或 [pixls.us 论坛](https://discuss.pixls.us/c/software/darktable/19)上回答问题 * 在[开发者 Matrix 聊天室](https://matrix.to/#/#darktable-dev:matrix.org)分享您的想法 * 测试[发布版本](https://www.darktable.org/install/) * 审查 [Pull Request](https://github.com/darktable-org/darktable/pulls) * 开始[参与 darktable 开发](https://www.darktable.org/development/)并查看[开发者指南](https://github.com/darktable-org/darktable/wiki/Developer's-guide) ## 常见问题 ### 为什么我的相机在插入时没有被检测到？ 请检查您是否安装了最新的 [gphoto2 库](http://www.gphoto.org/ "gphoto2 homepage")，以便支持最新的相机。 ### 为什么在暗房中我的镜头没有被检测到/校正？ 镜头校正配置文件由 Lensfun 提供，它包含两部分：一个程序和一个数据库。 大多数 Linux 发行版都提供了足够新的程序版本， 但提供的数据库版本却已过时。如果 [Lensfun](https://lensfun.github.io/) 已正确安装，请在终端中运行以下命令来更新其数据库： ``` lensfun-update-data ``` 或者 ``` /usr/bin/g-lensfun-update-data ``` ### 为什么光台视图中的缩略图看起来与暗房视图中的预览不同？ 对于从未在 darktable 中编辑过的 RAW 文件（当您刚刚导入它们时），光台视图默认会显示由您的相机放入 RAW 文件中的 JPEG 预览。加载此 JPEG 文件速度更快，并在导入大量图像集合时使光台视图响应更迅速。 然而，这个 JPEG 缩略图是由相机固件使用专有算法处理过的， 其色彩、清晰度和对比度看起来可能与 darktable 处理出来的效果不同（后者是您在暗房视图中打开图像时看到的内容）。 相机制造商并未公布其固件中执行的像素处理细节， 因此它们的外观无法被其他软件完全或轻易地重现。 但是，一旦 RAW 图像在 darktable 中被编辑过， 光台缩略图就应该与暗房预览完全匹配，因为它们的处理方式是相同的。 如果您永远不想在光台视图中看到 RAW 文件内嵌的 JPEG 缩略图，您应该在“偏好设置” -> “光台”中，将“从指定尺寸起使用 RAW 文件替代内嵌的 JPEG”选项设置为“从不”。 ## Wiki * [GitHub Wiki](https://github.com/darktable-org/darktable/wiki "github wiki") * [开发者 Wiki](https://github.com/darktable-org/darktable/wiki/Developer's-guide "darktable developer wiki") ## 社区 * [pixls.us 上的 Darktable 论坛](https://discuss.pixls.us/c/software/darktable/19)

标签：C/C++, RAW图像处理, rizin, Veh, 事务性I/O, 图像编辑, 客户端加密, 摄影工作流, 照片管理