nix.dev/source/reference/pinning-nixpkgs.md

(ref-pinning-nixpkgs)=

# Pinning Nixpkgs

Specifying remote Nix expressions, such as the one provided by Nixpkgs, can be done in several ways:

- [`$NIX_PATH` environment variable](https://nix.dev/manual/nix/2.18/command-ref/env-common.html#env-NIX_PATH)
- [`-I` option](https://nix.dev/manual/nix/2.18/command-ref/opt-common.html#opt-I) to most of commands like `nix-build`, `nix-shell`, etc.
- [`fetchurl`](https://nix.dev/manual/nix/2.18/language/builtins.html#builtins-fetchurl), [`fetchTarball`](https://nix.dev/manual/nix/2.18/language/builtins.html#builtins-fetchTarball), [`fetchGit`](https://nix.dev/manual/nix/2.18/language/builtins.html#builtins-fetchGit) or [Nixpkgs fetchers](https://nixos.org/manual/nixpkgs/stable/#chap-pkgs-fetchers) in Nix expressions

## Possible URL values

- Local file path:

  ```
  ./path/to/expression.nix
  ```

  Using `./.` means that the expression is located in a file `default.nix` in the current directory.

- Pinned to a specific commit:

  ```
  https://github.com/NixOS/nixpkgs/archive/eabc38219184cc3e04a974fe31857d8e0eac098d.tar.gz
  ```

- Using the latest channel version, meaning all tests have passed:

  ```
  http://nixos.org/channels/nixos-22.11/nixexprs.tar.xz
  ```

- Shorthand syntax for channels:

  ```
  channel:nixos-22.11
  ```

- Using the latest channel version, hosted by GitHub:

  ```
  https://github.com/NixOS/nixpkgs/archive/nixos-22.11.tar.gz
  ```

- Using the latest commit on the release branch, but not tested yet:

  ```
  https://github.com/NixOS/nixpkgs/archive/release-21.11.tar.gz
  ```

## Examples

- ```shell-session
  $ nix-build -I ~/dev
  ```

- ```shell-session
  $ nix-build -I nixpkgs=http://nixos.org/channels/nixos-22.11/nixexprs.tar.xz
  ```

- ```shell-session
  $ nix-build -I nixpkgs=channel:nixos-22.11
  ```

- ```shell-session
  $ NIX_PATH=nixpkgs=http://nixos.org/channels/nixos-22.11/nixexprs.tar.xz nix-build
  ```

- ```shell-session
  $ NIX_PATH=nixpkgs=channel:nixos-22.11 nix-build
  ```

- In the Nix language:

  ```nix
  let
    pkgs = import (fetchTarball "https://github.com/NixOS/nixpkgs/archive/nixos-22.11.tar.gz") {};
  in pkgs.stdenv.mkDerivation { ... }
  ```
Convert reference/*.rst to .md 2021-12-10 07:24:12 -05:00			`(ref-pinning-nixpkgs)=`

			`# Pinning Nixpkgs`

fixups to pinning overview remove the NixOS example, as the sample has lots of caveats, such as having to rebuild NixOS a second time to make it effective. 2023-02-16 00:23:33 -05:00			`Specifying remote Nix expressions, such as the one provided by Nixpkgs, can be done in several ways:`
Convert reference/*.rst to .md 2021-12-10 07:24:12 -05:00
update all links to the Nix manual 2023-11-01 22:41:54 -04:00			- [`$NIX_PATH` environment variable](https://nix.dev/manual/nix/2.18/command-ref/env-common.html#env-NIX_PATH)
			- [`-I` option](https://nix.dev/manual/nix/2.18/command-ref/opt-common.html#opt-I) to most of commands like `nix-build`, `nix-shell`, etc.
			- [`fetchurl`](https://nix.dev/manual/nix/2.18/language/builtins.html#builtins-fetchurl), [`fetchTarball`](https://nix.dev/manual/nix/2.18/language/builtins.html#builtins-fetchTarball), [`fetchGit`](https://nix.dev/manual/nix/2.18/language/builtins.html#builtins-fetchGit) or [Nixpkgs fetchers](https://nixos.org/manual/nixpkgs/stable/#chap-pkgs-fetchers) in Nix expressions
turn anti-patterns into best practices make generous use of admonitions 2023-05-11 23:45:19 -04:00
			`## Possible URL values`
Convert reference/*.rst to .md 2021-12-10 07:24:12 -05:00
turn anti-patterns into best practices make generous use of admonitions 2023-05-11 23:45:19 -04:00			`- Local file path:`
Convert reference/*.rst to .md 2021-12-10 07:24:12 -05:00
turn anti-patterns into best practices make generous use of admonitions 2023-05-11 23:45:19 -04:00			```
			`./path/to/expression.nix`
			```
fixups to pinning overview remove the NixOS example, as the sample has lots of caveats, such as having to rebuild NixOS a second time to make it effective. 2023-02-16 00:23:33 -05:00
fix missing word "in" 2023-12-05 08:24:11 -05:00			Using `./.` means that the expression is located in a file `default.nix` in the current directory.
fixups to pinning overview remove the NixOS example, as the sample has lots of caveats, such as having to rebuild NixOS a second time to make it effective. 2023-02-16 00:23:33 -05:00
turn anti-patterns into best practices make generous use of admonitions 2023-05-11 23:45:19 -04:00			`- Pinned to a specific commit:`
fixups to pinning overview remove the NixOS example, as the sample has lots of caveats, such as having to rebuild NixOS a second time to make it effective. 2023-02-16 00:23:33 -05:00
			```
			`https://github.com/NixOS/nixpkgs/archive/eabc38219184cc3e04a974fe31857d8e0eac098d.tar.gz`
			```

turn anti-patterns into best practices make generous use of admonitions 2023-05-11 23:45:19 -04:00			`- Using the latest channel version, meaning all tests have passed:`
fixups to pinning overview remove the NixOS example, as the sample has lots of caveats, such as having to rebuild NixOS a second time to make it effective. 2023-02-16 00:23:33 -05:00
			```
			`http://nixos.org/channels/nixos-22.11/nixexprs.tar.xz`
			```

fix typos, remove superfluous ellipses 2023-07-21 05:36:25 -04:00			`- Shorthand syntax for channels:`
fixups to pinning overview remove the NixOS example, as the sample has lots of caveats, such as having to rebuild NixOS a second time to make it effective. 2023-02-16 00:23:33 -05:00
			```
turn anti-patterns into best practices make generous use of admonitions 2023-05-11 23:45:19 -04:00			`channel:nixos-22.11`
fixups to pinning overview remove the NixOS example, as the sample has lots of caveats, such as having to rebuild NixOS a second time to make it effective. 2023-02-16 00:23:33 -05:00			```

turn anti-patterns into best practices make generous use of admonitions 2023-05-11 23:45:19 -04:00			`- Using the latest channel version, hosted by GitHub:`
fixups to pinning overview remove the NixOS example, as the sample has lots of caveats, such as having to rebuild NixOS a second time to make it effective. 2023-02-16 00:23:33 -05:00
			```
			`https://github.com/NixOS/nixpkgs/archive/nixos-22.11.tar.gz`
			```

turn anti-patterns into best practices make generous use of admonitions 2023-05-11 23:45:19 -04:00			`- Using the latest commit on the release branch, but not tested yet:`
fixups to pinning overview remove the NixOS example, as the sample has lots of caveats, such as having to rebuild NixOS a second time to make it effective. 2023-02-16 00:23:33 -05:00
			```
			`https://github.com/NixOS/nixpkgs/archive/release-21.11.tar.gz`
			```
Convert reference/*.rst to .md 2021-12-10 07:24:12 -05:00
			`## Examples`

*: fix editorconfig errors 2023-10-06 04:59:27 -04:00			- ```shell-session
Make code blocks consistent Illustration of shell sessions or terminals should use shell-session. Entire expressions should be encapsulated in code blocks, not inline code. 2022-11-08 11:37:41 -05:00			`$ nix-build -I ~/dev`
			```
Convert reference/*.rst to .md 2021-12-10 07:24:12 -05:00
Make code blocks consistent Illustration of shell sessions or terminals should use shell-session. Entire expressions should be encapsulated in code blocks, not inline code. 2022-11-08 11:37:41 -05:00			- ```shell-session
turn anti-patterns into best practices make generous use of admonitions 2023-05-11 23:45:19 -04:00			`$ nix-build -I nixpkgs=http://nixos.org/channels/nixos-22.11/nixexprs.tar.xz`
Make code blocks consistent Illustration of shell sessions or terminals should use shell-session. Entire expressions should be encapsulated in code blocks, not inline code. 2022-11-08 11:37:41 -05:00			```
Convert reference/*.rst to .md 2021-12-10 07:24:12 -05:00
fixups to pinning overview remove the NixOS example, as the sample has lots of caveats, such as having to rebuild NixOS a second time to make it effective. 2023-02-16 00:23:33 -05:00			- ```shell-session
Fix typo (#619) Remove trailing backtick. 2023-06-26 18:12:38 -04:00			`$ nix-build -I nixpkgs=channel:nixos-22.11`
fixups to pinning overview remove the NixOS example, as the sample has lots of caveats, such as having to rebuild NixOS a second time to make it effective. 2023-02-16 00:23:33 -05:00			```

Make code blocks consistent Illustration of shell sessions or terminals should use shell-session. Entire expressions should be encapsulated in code blocks, not inline code. 2022-11-08 11:37:41 -05:00			- ```shell-session
fix typos, remove superfluous ellipses 2023-07-21 05:36:25 -04:00			`$ NIX_PATH=nixpkgs=http://nixos.org/channels/nixos-22.11/nixexprs.tar.xz nix-build`
Make code blocks consistent Illustration of shell sessions or terminals should use shell-session. Entire expressions should be encapsulated in code blocks, not inline code. 2022-11-08 11:37:41 -05:00			```
Convert reference/*.rst to .md 2021-12-10 07:24:12 -05:00
fixups to pinning overview remove the NixOS example, as the sample has lots of caveats, such as having to rebuild NixOS a second time to make it effective. 2023-02-16 00:23:33 -05:00			- ```shell-session
fix typos, remove superfluous ellipses 2023-07-21 05:36:25 -04:00			`$ NIX_PATH=nixpkgs=channel:nixos-22.11 nix-build`
fixups to pinning overview remove the NixOS example, as the sample has lots of caveats, such as having to rebuild NixOS a second time to make it effective. 2023-02-16 00:23:33 -05:00			```

			`- In the Nix language:`
Convert reference/*.rst to .md 2021-12-10 07:24:12 -05:00
Make code blocks consistent Illustration of shell sessions or terminals should use shell-session. Entire expressions should be encapsulated in code blocks, not inline code. 2022-11-08 11:37:41 -05:00			```nix
Convert reference/*.rst to .md 2021-12-10 07:24:12 -05:00			`let`
Rewrite "Set up development environment" (#376) * Rewrite "Set up development environment" The previous version is specific to Python as it uses `buildPythonApplication` instead of `mkShell`. This one is more general but maintains the same Python Flask web application example. * Update pinning-nixpkgs to use 22.11 Co-authored-by: Valentin Gagarin <valentin.gagarin@tweag.io> 2022-12-09 22:33:06 -05:00			`pkgs = import (fetchTarball "https://github.com/NixOS/nixpkgs/archive/nixos-22.11.tar.gz") {};`
Make code blocks consistent Illustration of shell sessions or terminals should use shell-session. Entire expressions should be encapsulated in code blocks, not inline code. 2022-11-08 11:37:41 -05:00			`in pkgs.stdenv.mkDerivation { ... }`
Convert reference/*.rst to .md 2021-12-10 07:24:12 -05:00			```