diff --git a/doc/package-notes.xml b/doc/package-notes.xml
index e23593107d8..c93f99d256b 100644
--- a/doc/package-notes.xml
+++ b/doc/package-notes.xml
@@ -882,6 +882,33 @@ citrix_receiver.override {
     On NixOS it can be installed using the following expression:
 <programlisting>{ pkgs, ... }: {
   fonts.fonts = with pkgs; [ noto-fonts-emoji ];
+}</programlisting>
+   </para>
+  </section>
+ </section>
+ <section xml:id="dlib">
+  <title>DLib</title>
+
+  <para>
+    <link xlink:href="http://dlib.net/">DLib</link> is a modern, C++-based toolkit which
+    provides several machine learning algorithms.
+  </para>
+
+  <section xml:id="compiling-without-avx-support">
+   <title>Compiling without AVX support</title>
+
+   <para>
+     Especially older CPUs don't support
+     <link xlink:href="https://en.wikipedia.org/wiki/Advanced_Vector_Extensions">AVX</link>
+     (<abbrev>Advanced Vector Extensions</abbrev>) instructions that are used by DLib to
+     optimize their algorithms.
+   </para>
+
+   <para>
+    On the affected hardware errors like <literal>Illegal instruction</literal> will occur.
+    In those cases AVX support needs to be disabled:
+<programlisting>self: super: {
+  dlib = super.dlib.override { avxSupport = false; };
 }</programlisting>
    </para>
   </section>
diff --git a/pkgs/development/libraries/dlib/default.nix b/pkgs/development/libraries/dlib/default.nix
index a88b3f1b9b6..67a56855bb7 100644
--- a/pkgs/development/libraries/dlib/default.nix
+++ b/pkgs/development/libraries/dlib/default.nix
@@ -1,5 +1,8 @@
 { stdenv, lib, fetchFromGitHub, cmake, pkgconfig, libpng, libjpeg
 , guiSupport ? false, libX11
+
+  # see http://dlib.net/compile.html
+, avxSupport ? true
 }:
 
 stdenv.mkDerivation rec {
@@ -17,6 +20,8 @@ stdenv.mkDerivation rec {
     rm -rf dlib/external
   '';
 
+  cmakeFlags = [ "-DUSE_AVX_INSTRUCTIONS=${if avxSupport then "yes" else "no"}" ];
+
   enableParallelBuilding = true;
   nativeBuildInputs = [ cmake pkgconfig ];
   buildInputs = [ libpng libjpeg ] ++ lib.optional guiSupport libX11;
diff --git a/pkgs/development/python-modules/dlib/default.nix b/pkgs/development/python-modules/dlib/default.nix
index 90e2c526789..c200b6959b6 100644
--- a/pkgs/development/python-modules/dlib/default.nix
+++ b/pkgs/development/python-modules/dlib/default.nix
@@ -1,12 +1,17 @@
-{ buildPythonPackage, dlib, python, pytest }:
+{ buildPythonPackage, dlib, python, pytest, avxSupport ? true }:
 
 buildPythonPackage {
   inherit (dlib) name src nativeBuildInputs buildInputs meta;
 
+  # although AVX can be enabled, we never test with it. Some Hydra machines
+  # fail because of this, however their build results are probably used on hardware
+  # with AVX support.
   checkPhase = ''
     ${python.interpreter} nix_run_setup test --no USE_AVX_INSTRUCTIONS
   '';
 
+  setupPyBuildFlags = [ "--${if avxSupport then "yes" else "no"} USE_AVX_INSTRUCTIONS" ];
+
   patches = [ ./build-cores.patch ];
 
   checkInputs = [ pytest ];