path: root/doc/configuration.xml

<chapter xmlns="http://docbook.org/ns/docbook"
         xmlns:xlink="http://www.w3.org/1999/xlink"
         xml:id="chap-packageconfig">

<title>Global configuration</title>

<para>Nix comes with certain defaults about what packages can and
cannot be installed, based on a package's metadata. By default, Nix
will prevent installation if any of the following criteria are
true:</para>

<itemizedlist>
  <listitem><para>The package is thought to be broken, and has had
  its <literal>meta.broken</literal> set to
  <literal>true</literal>.</para></listitem>

  <listitem><para>The package's <literal>meta.license</literal> is set
  to a license which is considered to be unfree.</para></listitem>

  <listitem><para>The package has known security vulnerabilities but
  has not or can not be updated for some reason, and a list of issues
  has been entered in to the package's
  <literal>meta.knownVulnerabilities</literal>.</para></listitem>
</itemizedlist>

<para>Note that all this is checked during evaluation already,
and the check includes any package that is evaluated.
In particular, all build-time dependencies are checked.
<literal>nix-env -qa</literal> will (attempt to) hide any packages
that would be refused.
</para>

<para>Each of these criteria can be altered in the nixpkgs
configuration.</para>

<para>The nixpkgs configuration for a NixOS system is set in the
<literal>configuration.nix</literal>, as in the following example:
<programlisting>
{
  nixpkgs.config = {
    allowUnfree = true;
  };
}
</programlisting>
However, this does not allow unfree software for individual users.
Their configurations are managed separately.</para>

<para>A user's of nixpkgs configuration is stored in a user-specific
configuration file located at
<filename>~/.config/nixpkgs/config.nix</filename>. For example:
<programlisting>
{
  allowUnfree = true;
}
</programlisting>
</para>

<section xml:id="sec-allow-broken">
  <title>Installing broken packages</title>


  <para>There are two ways to try compiling a package which has been
  marked as broken.</para>

  <itemizedlist>
    <listitem><para>
      For allowing the build of a broken package once, you can use an
      environment variable for a single invocation of the nix tools:

      <programlisting>$ export NIXPKGS_ALLOW_BROKEN=1</programlisting>
    </para></listitem>

    <listitem><para>
      For permanently allowing broken packages to be built, you may
      add <literal>allowBroken = true;</literal> to your user's
      configuration file, like this:

<programlisting>
{
  allowBroken = true;
}
</programlisting>
    </para></listitem>
  </itemizedlist>
</section>

<section xml:id="sec-allow-unfree">
  <title>Installing unfree packages</title>

  <para>There are several ways to tweak how Nix handles a package
  which has been marked as unfree.</para>

  <itemizedlist>
    <listitem><para>
      To temporarily allow all unfree packages, you can use an
      environment variable for a single invocation of the nix tools:

      <programlisting>$ export NIXPKGS_ALLOW_UNFREE=1</programlisting>
    </para></listitem>

    <listitem><para>
      It is possible to permanently allow individual unfree packages,
      while still blocking unfree packages by default using the
      <literal>allowUnfreePredicate</literal> configuration
      option in the user configuration file.</para>

      <para>This option is a function which accepts a package as a
      parameter, and returns a boolean. The following example
      configuration accepts a package and always returns false:
<programlisting>
{
  allowUnfreePredicate = (pkg: false);
}
</programlisting>
      </para>

      <para>A more useful example, the following configuration allows
      only allows flash player and visual studio code:

<programlisting>
{
  allowUnfreePredicate = (pkg: elem (builtins.parseDrvName pkg.name).name [ "flashplayer" "vscode" ]);
}
</programlisting>
    </para></listitem>

    <listitem>
      <para>It is also possible to whitelist and blacklist licenses
      that are specifically acceptable or not acceptable, using
      <literal>whitelistedLicenses</literal> and
      <literal>blacklistedLicenses</literal>, respectively.
      </para>

      <para>The following example configuration whitelists the
      licenses <literal>amd</literal> and <literal>wtfpl</literal>:

<programlisting>
{
  whitelistedLicenses = with stdenv.lib.licenses; [ amd wtfpl ];
}
</programlisting>
      </para>

      <para>The following example configuration blacklists the
      <literal>gpl3</literal> and <literal>agpl3</literal> licenses:

<programlisting>
{
  blacklistedLicenses = with stdenv.lib.licenses; [ agpl3 gpl3 ];
}
</programlisting>
      </para>
    </listitem>
  </itemizedlist>

  <para>A complete list of licenses can be found in the file
  <filename>lib/licenses.nix</filename> of the nixpkgs tree.</para>
</section>


<section xml:id="sec-allow-insecure">
  <title>
    Installing insecure packages
  </title>

  <para>There are several ways to tweak how Nix handles a package
  which has been marked as insecure.</para>

  <itemizedlist>
    <listitem><para>
      To temporarily allow all insecure packages, you can use an
      environment variable for a single invocation of the nix tools:

      <programlisting>$ export NIXPKGS_ALLOW_INSECURE=1</programlisting>
    </para></listitem>

    <listitem><para>
      It is possible to permanently allow individual insecure
      packages, while still blocking other insecure packages by
      default using the <literal>permittedInsecurePackages</literal>
      configuration option in the user configuration file.</para>

      <para>The following example configuration permits the
      installation of the hypothetically insecure package
      <literal>hello</literal>, version <literal>1.2.3</literal>:
<programlisting>
{
  permittedInsecurePackages = [
    "hello-1.2.3"
  ];
}
</programlisting>
      </para>
    </listitem>

    <listitem><para>
      It is also possible to create a custom policy around which
      insecure packages to allow and deny, by overriding the
      <literal>allowInsecurePredicate</literal> configuration
      option.</para>

      <para>The <literal>allowInsecurePredicate</literal> option is a
      function which accepts a package and returns a boolean, much
      like <literal>allowUnfreePredicate</literal>.</para>

      <para>The following configuration example only allows insecure
      packages with very short names:

<programlisting>
{
  allowInsecurePredicate = (pkg: (builtins.stringLength (builtins.parseDrvName pkg.name).name) &lt;= 5);
}
</programlisting>
      </para>

      <para>Note that <literal>permittedInsecurePackages</literal> is
      only checked if <literal>allowInsecurePredicate</literal> is not
      specified.
    </para></listitem>
  </itemizedlist>
</section>

<!--============================================================-->

<section xml:id="sec-modify-via-packageOverrides"><title>Modify
packages via <literal>packageOverrides</literal></title>

<para>You can define a function called
<varname>packageOverrides</varname> in your local
<filename>~/.config/nixpkgs/config.nix</filename> to overide nix packages.  It
must be a function that takes pkgs as an argument and return modified
set of packages.

<programlisting>
{
  packageOverrides = pkgs: rec {
    foo = pkgs.foo.override { ... };
  };
}
</programlisting>

</para>

</section>


</chapter>