Skip to content

Latest commit

 

History

History
416 lines (298 loc) · 17.8 KB

README.md

File metadata and controls

416 lines (298 loc) · 17.8 KB
Raw

icon darktable GitHub Workflow Status (branch) CII Best Practices

darktable is an open source photography workflow application and non-destructive raw developer. A virtual lighttable and darkroom for photographers. It manages your digital negatives in a database, lets you view them through a zoomable lighttable and enables you to develop raw images, enhance them and export them to local or remote storage.

darktable is not a free Adobe® Lightroom® replacement.

https://www.darktable.org/

Table of Contents

  1. Documentation
  2. Website
  3. Requirements
  4. Installing
  5. Updating from older versions
  6. Getting extensions
  7. Building
  8. Using
  9. Contributing
  10. FAQ
  1. Wiki
  2. Mailing lists

Documentation

The darktable user manual is maintained in the dtdocs repository.

Lua API documentation is maintained in the luadocs repository.

Website

The website https://www.darktable.org/ is maintained in the dtorg repository.

Requirements

Supported platforms

  • Linux (64 bits)
  • Free BSD (64 bits)
  • Windows 8 (64 bits), Windows 10 (64 bits)
  • macOS

32 bits platforms are not officially supported, they might or might not work.

Windows support is still young and suffers from bugs that do not affect Linux. If possible, prefer using darktable on Linux.

Hardware

(workable minimum / recommended minimum):

  • RAM: 4 GB / 8 GB
  • CPU: Intel Pentium 4 / Intel Core i5 4×2.4 GHz
  • GPU: none / Nvidia with 1024 CUDA cores, 4 GB, OpenCL 1.2 compatible
  • free disk space: 250 MB / 1 GB

darktable can run on lightweight configurations (even Raspberry Pi), but expect modules like denoising, local contrast, contrast equalizer, retouch or liquify to be slow beyond usable.

GPU is not mandatory but strongly recommended for a smoother experience. Nvidia GPU are recommended for safety because some AMD drivers behave unreliably with some modules (local contrast).

Installing

If the latest release is still not available as a pre-built package for your distribution, you can build the software yourself following the instructions below.

Latest release

3.6.0 (stable)

When using a pre-built package, ensure it has been built with Lua, OpenCL, OpenMP and Colord support. These are optional and will not prevent darktable from running if missing, but their absence will degrade user experience. Noticeably, some Flatpak, Snap and Appimage packages lack OpenCL and Lua support.

Development snapshot

The development snapshot is the state of the master branch at current time. It is intended for testing and is generally not safe. See the notes below for warnings and precautions about using the master branch.

Updating from older versions

When updating darktable from an older release, you need to install the newest version. Files will be preserved.

However, sometimes newer releases need to change the structure of the library database (containing the whole list of images known to darktable, with their editing history). You will then be prompted with a request to either upgrade the database or close the software.

The migration to a newer database structure/newer release means new and old edits will not be compatible with older versions of darktable. Upgrades are definitive. Newer versions are always compatible with older edits, but newer edits are generally not compatible with older versions.

darktable automatically backs up the library database when a new version upgrades it (in ~/.config/darktable/library.db-pre-3.0.0 for example), so you can revert to the previous release by restoring this backup if needed (simply rename it library.db).

If you try to open a newer database with an older software version, the parts of the edits done with new features will be discarded and you will lose them. This also applies to the sidecar XMP files.

If you plan to move regularly between 2 versions (new/unstable and old/stable) see below how to do it safely.

Getting extensions

Extensions and plugins use the Lua scripting language and can be downloaded here. Lua support is optional in darktable, ensure you have the interpreter lua and its development files (package lua-dev or lua-devel, depending on distributions) installed on your system while building or ensure the package you are using has been built with this library.

Extensions allow exporting for various media and websites, merge/stack/blend HDR, panoramas or focus bracketing, apply AI-based facial recognition, manage tags and GPS data, etc.

Building

Dependencies

Compatible compilers:

  • Clang: 8, 9, 10
  • GCC: 8, 9, 10
  • Mingw64: 6, 7

Required dependencies minimal version:

  • CMake 3.10
  • Gtk 3.22
  • Glib 2.40
  • SQLite 3.15 (but 3.24 strongly recommended)

Optional dependencies minimal version:

  • OpenMP 4.5 (for CPU multi-threading and SIMD vectorization)
  • LLVM 3.9 (for OpenCL checks at compilation time)
  • OpenCL 1.2 (for GPU-accelerated computing)
  • Lua 5.3 (for plugins and extensions scripting)
  • libavif 0.7.2 (for AVIF import/export)
  • WebP 0.3.0 (for WebP exports)

Optional dependencies with no version requirement:

  • Gphoto2 (for camera tethering)
  • Lensfun (for lens automatic correction)
  • OpenEXR (for EXR import and export)
  • OpenJPEG (for Jpeg2000 export)
  • Colord, Xatom (for system display color profile fetching)
  • G'Mic (for HaldcLUT support)
  • PortMidi (for MIDI input support)
  • SDL2 (for gamepad input support)

To install all the dependencies on Linux systems, you may use the source repositories of your distribution (provided they are up-to-date):

Fedora and RHEL

sudo dnf builddep darktable

OpenSuse

sudo zypper si -d darktable

Ubuntu

sed -e '/^#\sdeb-src /s/^# *//;t;d' "/etc/apt/sources.list" \
  | sudo tee /etc/apt/sources.list.d/darktable-sources-tmp.list > /dev/null \
  && (
    sudo apt-get update
    sudo apt-get build-dep darktable
  )
sudo rm /etc/apt/sources.list.d/darktable-sources-tmp.list

Debian

sudo apt-get build-dep darktable

Install missing dependencies

If mandatory dependencies are missing on your system, building the software will fail with errors like Package XXX has not been found or Command YYY has no provider on this system. What you need to do, then, is to search which package provides the required missing package or command in your distribution, then install it. This can usually be done in your package manager (not the applications manager customarily provided by default in your distribution) or on the internet with a search engine. You may need to install a package manager first (like Synaptic on Debian/Ubuntu, or DNF Dragora on Fedora/RHEL).

This process might be tedious but you only need to do it once. See this page on building darktable for one-line commands that will install most dependencies on the most frequent Linux distributions.

Get the source

Master branch (unstable)

The master branch contains the latest version of the source code and is intended:

  • as a working base for developers,
  • for beta-testers to chase bugs,
  • for users willing to sacrifice stability for new features without waiting for the next release.

The master branch comes with no guarantee of stability, might corrupt your database and XMP files, might result in loss of data and edits history or temporarily break compatibility with previous versions and commits.

How dangerous is it? Most of the time, it is fairly stable. As with any rolling-release kind of deployment, bugs appear more often but are fixed faster too. But sometimes, they result in losses or inconsistencies in the editing history of your pictures, which is fine if you don't need to open your edits again in the future, but maybe not if you manage an estate.

After backing up your ~/.config/darktable directory as well as the sidecar .XMP files of the pictures you will open with the master branch, you may get the source:

git clone --recurse-submodules --depth 1 https://github.com/darktable-org/darktable.git
cd darktable

See below (in "Using") how to start a test install of the unstable version without damaging your regular stable install and files.

Latest stable release

3.6.0

darktable project releases one major version every year, for Christmas, tagged with even numbers (e.g., 2.2, 2.4, 2.6, 3.0). Minor revisions are tagged with a third digit (e.g., 3.0.1, 3.0.2) and mostly provide bug fixes and minor new features. You may want to compile these stable releases yourself to get better performance for your particular computer:

git clone --recurse-submodules --depth 1 https://github.com/darktable-org/darktable.git
cd darktable
git fetch --tags
git checkout tags/release-3.6.0

Get submodules

Note that LibXCF, OpenCL, rawspeed, and whereami are tracked via a git submodule, so after checking-out the darktable, you need to update/checkout them:

git submodule update --init

Compile

Easy way

WARNING: in case you have already built darktable in the past, don't forget to remove entirely (rm -R) the build and /opt/darktable directories to avoid conflicting files from different versions. Many weird behaviours and transient bugs have been reported that can be tracked down to the building cache not properly invalidating the changed dependencies, so the safest way is to completely remove previously built binaries and restart from scratch.

darktable provides a shell script that automatically takes care of the building on Linux and macOS for classic cases in a single command.

./build.sh --prefix /opt/darktable --build-type Release --install --sudo

If you want to install a test version alongside your regular/stable version, change the install prefix:

./build.sh --prefix /opt/darktable-test --build-type Release --install --sudo

This builds the software for your architecture only, with:

  • -O3 optimization level,
  • SSE/AVX support if detected,
  • OpenMP support (multi-threading and vectorization) if detected,
  • OpenCL support (GPU offloading) if detected,
  • Lua scripting support if detected.

Manual way

You can alternatively use the manual building to pass on custom arguments.

Linux/macOS
mkdir build/
cd build/
cmake -DCMAKE_INSTALL_PREFIX=/opt/darktable/ ..
make
sudo make install
Windows

See https://github.com/darktable-org/darktable/blob/master/packaging/windows/BUILD.md

Using

Test/unstable version

To use a test version of darktable without damaging your regular/stable version files and database, start darktable in a terminal with:

/opt/darktable-test/bin/darktable --configdir "~/.config/darktable-test"

and ensure to disable the option "write sidecar file for each image" in preferences -> storage -> XMP. This way, your regular/stable version will save its configuration files in ~/.config/darktable, as usual, and the test/unstable one in ~/.config/darktable-test, so they will not produce database conflicts.

Regular/stable version

Simply launch it from your desktop application menu, or in terminal, run darktable or /opt/darktable/bin/darktable. If the installation did not create a launcher in your applications menu, run:

sudo ln -s /opt/darktable/share/applications/darktable.desktop /usr/share/applications/darktable.desktop

You may find darktable configuration files in ~/.config/darktable. If you are having crashes at startup, try launching darktable without OpenCL with darktable --conf opencl=FALSE.

Further reading

There is a comprehensive list of build instructions for Ubuntu/Debian related Linux distributions or for Fedora and related ones distributions. These build instructions could easily be adapted to all other distributions

Contributing

FAQ

Why is my camera not detected when plugged-in ?

Check that you have the latest gphoto2 library installed in order to support the newest cameras.

Why is my lens not detected/corrected in darkroom ?

Lens correction profiles are provided by Lensfun, which has 2 parts: a program and a database. Most Linux distributions provide a recent enough version of the program, but provide an outdated version of the database. If Lensfun is correctly installed, then update its database in a terminal by running:

lensfun-update-data

or alternatively

/usr/bin/g-lensfun-update-data

Why are the thumbnails in lighttable looking different than the preview in darkroom ?

For RAW files never edited before in darktable (when you only imported them), the lighttable uses by default the embedded JPEG thumbnail put in the RAW file by your camera. Loading this JPEG file is faster and makes the lighttable more responsive when importing large collections of images.

However, this JPEG thumbnail is processed by the firmware of the camera, with proprietary algorithms, and colors, sharpness and contrast might not look the same as darktable processing, which is what you see when opening the darkroom. Notice camera's manufacturers don't publish the pixel cuisine they perform in their firmware so their look is not exactly nor easily reproducible externally.

However, once RAW images have been previously edited in darktable, the lighttable thumbnail should match exactly the darkroom preview because they are processed the same.

To never see the embedded JPEG thumbnail in lighttable, for RAW files, you can check the option "don't use embedded preview JPEG but half-size raw" in preferences -> lighttable.

Wiki

Mailing lists