https://github.com/nix-community/NUR/issues/755
The Nix User Repository (NUR) is a community-driven meta repository for Nix packages. It provides access to user repositories that contain package descriptions (Nix expressions) and allows you to install packages by referencing them via attributes. In contrast to Nixpkgs, packages are built from source and are not reviewed by any Nixpkgs member.
The NUR was created to share new packages from the community in a faster and more decentralized way.
NUR automatically checks its list of repositories and performs evaluation checks before it propagates the updates.
First include NUR in your packageOverrides
:
To make NUR accessible for your login user, add the following to ~/.config/nixpkgs/config.nix
:
{
packageOverrides = pkgs: {
nur = import (builtins.fetchTarball "https://github.com/nix-community/NUR/archive/master.tar.gz") {
inherit pkgs;
};
};
}
For NixOS add the following to your /etc/nixos/configuration.nix
Notice: If you want to use NUR in nix-env, home-manager or in nix-shell you also need NUR in ~/.config/nixpkgs/config.nix
as shown above!
{
nixpkgs.config.packageOverrides = pkgs: {
nur = import (builtins.fetchTarball "https://github.com/nix-community/NUR/archive/master.tar.gz") {
inherit pkgs;
};
};
}
Using builtins.fetchTarball
without a sha256 will only cache the download for 1 hour by default, so you need internet access almost every time you build something. You can pin the version if you don't want that:
builtins.fetchTarball {
# Get the revision by choosing a version from https://github.com/nix-community/NUR/commits/master
url = "https://github.com/nix-community/NUR/archive/3a6a6f4da737da41e27922ce2cfacf68a109ebce.tar.gz";
# Get the hash by running `nix-prefetch-url --unpack <url>` on the above url
sha256 = "04387gzgl8y555b3lkz9aiw9xsldfg4zmzp930m62qw8zbrvrshd";
}
Then packages can be used or installed from the NUR namespace.
$ nix-shell -p nur.repos.mic92.hello-nur
nix-shell> hello
Hello, NUR!
or
$ nix-env -f '<nixpkgs>' -iA nur.repos.mic92.hello-nur
or
# configuration.nix
environment.systemPackages = with pkgs; [
nur.repos.mic92.hello-nur
];
Each contributor can register their repository under a name and is responsible for its content.
NUR does not check the repository for malicious content on a regular basis and it is recommended to check the expressions before installing them.
Using overlays and modules from NUR in your configuration is fairly straight forward.
In your flake.nix add nur.nixosModules.nur
to your module list:
{
inputs.nur.url = github:nix-community/NUR;
outputs = { self, nixpkgs, nur }: {
nixosConfigurations.myConfig = nixpkgs.lib.nixosSystem {
# ...
modules = [
nur.nixosModules.nur
# This adds a nur configuration option.
# Use `config.nur` for packages like this:
# ({ config, ... }: {
# environment.systemPackages = [ config.nur.repos.mic92.hello-nur ];
# })
];
};
};
}
You cannot use config.nur
for importing NixOS modules from NUR as this will lead to infinite recursion errors.
Instead use:
{
inputs.nur.url = "github:nix-community/NUR";
outputs = { self, nixpkgs, nur }: rec {
nixosConfigurations.laptop = nixpkgs.lib.nixosSystem {
system = "x86_64-linux";
modules = [
{ nixpkgs.overlays = [ nur.overlay ]; }
({ pkgs, ... }:
let
nur-no-pkgs = import nur {
nurpkgs = import nixpkgs { system = "x86_64-linux"; };
};
in {
imports = [ nur-no-pkgs.repos.iopq.modules.xraya ];
services.xraya.enable = true;
})
#./configuration.nix or other imports here
];
};
};
}
If you intend to use modules, overlays or library functions in your NixOS configuration.nix, you need to take care not to introduce infinite recursion. Specifically, you need to import NUR like this in the modules:
{ pkgs, config, lib, ... }:
let
nur-no-pkgs = import (builtins.fetchTarball "https://github.com/nix-community/NUR/archive/master.tar.gz") {};
in {
imports = [
nur-no-pkgs.repos.paul.modules.foo
];
nixpkgs.overlays = [
nur-no-pkgs.repos.ben.overlays.bar
];
}
Integrating with Home Manager can be done by adding your modules to the imports
attribute.
You can then configure your services like usual.
let
nur-no-pkgs = import (builtins.fetchTarball "https://github.com/nix-community/NUR/archive/master.tar.gz") {};
in
{
imports = lib.attrValues nur-no-pkgs.repos.moredhel.hmModules.rawModules;
services.unison = {
enable = true;
profiles = {
org = {
src = "/home/moredhel/org";
dest = "/home/moredhel/org.backup";
extraArgs = "-batch -watch -ui text -repeat 60 -fat";
};
};
};
}
You can find all packages using Packages search for NUR or search our nur-combined repository, which contains all nix expressions from all users, via github.
First, create a repository that contains a default.nix
in its top-level directory.
We also provide a repository template that contains
a prepared directory structure.
DO NOT import packages for example with import <nixpkgs> {};
.
Instead take all dependency you want to import from Nixpkgs from the given pkgs
argument.
Each repository should return a set of Nix derivations:
{ pkgs }:
{
hello-nur = pkgs.callPackage ./hello-nur {};
}
In this example hello-nur
would be a directory containing a default.nix
:
{ stdenv, fetchurl, lib }:
stdenv.mkDerivation rec {
pname = "hello";
version = "2.10";
src = fetchurl {
url = "mirror://gnu/hello/${pname}-${version}.tar.gz";
sha256 = "0ssi1wpaf7plaswqqjwigppsg5fyh99vdlb9kzl7c9lng89ndq1i";
};
postPatch = ''
sed -i -e 's/Hello, world!/Hello, NUR!/' src/hello.c
'';
# fails due to patch
doCheck = false;
meta = with lib; {
description = "A program that produces a familiar, friendly greeting";
longDescription = ''
GNU Hello is a program that prints "Hello, world!" when you run it.
It is fully customizable.
'';
homepage = https://www.gnu.org/software/hello/manual/;
changelog = "https://git.savannah.gnu.org/cgit/hello.git/plain/NEWS?h=v${version}";
license = licenses.gpl3Plus;
maintainers = [ maintainers.eelco ];
platforms = platforms.all;
};
}
You can use nix-shell
or nix-build
to build your packages:
$ nix-shell --arg pkgs 'import <nixpkgs> {}' -A hello-nur
nix-shell> hello
nix-shell> find $buildInputs
$ nix-build --arg pkgs 'import <nixpkgs> {}' -A hello-nur
For development convenience, you can also set a default value for the pkgs argument:
{ pkgs ? import <nixpkgs> {} }:
{
hello-nur = pkgs.callPackage ./hello-nur {};
}
$ nix-build -A hello-nur
Add your own repository to the repos.json
of NUR:
$ git clone --depth 1 https://github.com/nix-community/NUR
$ cd NUR
edit the file repos.json
:
{
"repos": {
"mic92": {
"url": "https://github.com/Mic92/nur-packages"
},
"<fill-your-repo-name>": {
"url": "https://github.com/<your-user>/<your-repo>"
}
}
}
At the moment, each URL must point to a git repository. By running bin/nur update
the corresponding repos.json.lock
is updated and the repository is tested. This will
also perform an evaluation check, which must be passed for your repository. Commit the changed
repos.json
but NOT repos.json.lock
$ ./bin/nur format-manifest # ensure repos.json is sorted alphabetically
$ git add repos.json
$ git commit -m "add <your-repo-name> repository"
$ git push
and open a pull request towards https://github.com/nix-community/NUR.
At the moment repositories should be buildable on Nixpkgs unstable. Later we will add options to also provide branches for other Nixpkgs channels.
To use a different file instead of default.nix
to load packages from, set the file
option to a path relative to the repository root:
{
"repos": {
"mic92": {
"url": "https://github.com/Mic92/nur-packages",
"file": "subdirectory/default.nix"
}
}
}
By default, we only check for repository updates once a day with an automatic
github action to update our lock file repos.json.lock
.
To update NUR faster, you can use our service at https://nur-update.nix-community.org/
after you have pushed an update to your repository, e.g.:
curl -XPOST https://nur-update.nix-community.org/update?repo=mic92
Check out the github page for further details
With every build triggered via the URL hook, all repositories will be evaluated.Only if the evaluation does not contain errors the repository revision for the user is updated. Typical evaluation errors are:
builtins.fetchGit
use pkgs.fetchgit
)You can find out if your evaluation succeeded by checking the latest build job.
In your nur-packages/
folder, run the check evaluation task
nix-env -f . -qa \* --meta \
--allowed-uris https://static.rust-lang.org \
--option restrict-eval true \
--option allow-import-from-derivation true \
--drv-path --show-trace \
-I nixpkgs=$(nix-instantiate --find-file nixpkgs) \
-I ./ \
--json | jq -r 'values | .[].name'
On success, this shows a list of your packages
To fetch git submodules in repositories set submodules
:
{
"repos": {
"mic92": {
"url": "https://github.com/Mic92/nur-packages",
"submodules": true
}
}
}
It is also possible to define more than just packages. In fact any Nix expression can be used.
To make NixOS modules, overlays and library functions more discoverable, we propose to put them in their own namespace within the repository. This allows us to make them later searchable, when the indexer is ready.
NixOS modules should be placed in the modules
attribute:
{ pkgs }: {
modules = import ./modules;
}
# modules/default.nix
{
example-module = ./example-module.nix;
}
An example can be found here. Modules should be defined as paths, not functions, to avoid conflicts if imported from multiple locations.
For overlays use the overlays
attribute:
# default.nix
{
overlays = {
hello-overlay = import ./hello-overlay;
};
}
# hello-overlay/default.nix
self: super: {
hello = super.hello.overrideAttrs (old: {
separateDebugInfo = true;
});
}
Put reusable nix functions that are intend for public use in the lib
attribute:
{ pkgs }:
with pkgs.lib;
{
lib = {
hexint = x: hexvals.${toLower x};
hexvals = listToAttrs (imap (i: c: { name = c; value = i - 1; })
(stringToCharacters "0123456789abcdef"));
};
}
You can override repositories using repoOverrides
argument.
This allows to test changes before publishing.
{
packageOverrides = pkgs: {
nur = import (builtins.fetchTarball "https://github.com/nix-community/NUR/archive/master.tar.gz") {
inherit pkgs;
repoOverrides = {
mic92 = import ../nur-packages { inherit pkgs; };
## remote locations are also possible:
# mic92 = import (builtins.fetchTarball "https://github.com/your-user/nur-packages/archive/master.tar.gz") { inherit pkgs; };
};
};
};
}
The repo must be a valid package repo, i.e. its root contains a default.nix
file.
Experimental Note that flake support is still experimental and might change in future in a backwards incompatible way.
You can override repositories in two ways:
With packageOverrides
{
inputs.nur.url = "github:nix-community/NUR";
inputs.paul.url = "path:/some_path/nur-paul"; # example: a local nur.repos.paul for development
outputs = {self, nixpkgs, nur, paul }: {
system = "x86_64-linux";
nurpkgs = import nixpkgs { inherit system; };
...
modules = [
{
nixpkgs.config.packageOverrides = pkgs: {
nur = import nur {
inherit pkgs nurpkgs;
repoOverrides = { paul = import paul { inherit pkgs; }; };
};
};
}
];
...
}
{
modules = [
{
nixpkgs.overlays = [
(final: prev: {
nur = import nur {
nurpkgs = prev;
pkgs = prev;
repoOverrides = { paul = import paul { pkgs = prev; }; };
};
})
];
}
...
];
}
The repo must contains a flake.nix
file to addition of default.nix
: flake.nix example
nur-no-pkgs
(from previous Flake Support section) as:
{
nur-no-pkgs = import nur {
nurpkgs = import nixpkgs { system = "x86_64-linux"; };
repoOverrides = { paul = import paul { }; };
};
}
meta.broken
attribute to true otherwise.Examples for packages that could be in NUR:
To make it easier to review nix expression NUR makes it obvious where the package is coming from. If NUR would be an overlay malicious repositories could override existing packages. Also without coordination multiple overlays could easily introduce dependency cycles.
We have a matrix channel on #nur:nixos.org. Apart from that we also read posts on https://discourse.nixos.org.