NixOS & Flakes

https://nixos-and-flakes.thiscute.world/
Admin
An unofficial beginner-friendly book and tutorial for learning NixOS and Flakes in detail with...
Tokens:35,445
Snippets:191
Trust Score:7.7
Update:1 year ago
Show doc for...
Tokens:
Raw
### Using the FHS Environment to Run Binaries

Source: https://nixos-and-flakes.thiscute.world/best-practices/run-downloaded-binaries-on-nixos

This example demonstrates how to use the `fhs` command, created by the Nix configuration, to enter an FHS environment. Once inside this environment, which mimics a standard Linux setup, you can execute downloaded binaries. The example shows entering the shell, listing files in `/usr/bin`, and then attempting to run a binary named `./bin/code`.

```bash
# Activating FHS drops me into a shell that resembles a "normal" Linux environment.
(fhs) $ ls /usr/bin
# Try running a non-NixOS binary downloaded from the Internet.
(fhs) $ ./bin/code
```

--------------------------------

### NixOS Configuration Examples

Source: https://context7.com/context7/nixos-and-flakes_thiscute_world/llms.txt

Demonstrates different approaches to managing system and user packages in NixOS, including splitting profiles, using different Python versions, and overriding package dependencies.

```nix
# Solution 1: Split into different profiles
{
  # System profile
  environment.systemPackages = with pkgs; [
    lldb
  ];

  # User profile (home-manager)
  home.packages = with pkgs; [
    (python311.withPackages (ps: with ps; [
      ipython
      pandas
      requests
    ]))
  ];
}

# Solution 2: Use different Python version
{
  home.packages = with pkgs; [
    lldb
    (python310.withPackages (ps: with ps; [
      ipython
      pandas
    ]))
  ];
}

# Solution 3: Override package dependencies
{
  home.packages = with pkgs; [
    (lldb.override { python3 = python311; })
    (python311.withPackages (ps: with ps; [
      ipython
      pandas
    ]))
  ];
}
```

--------------------------------

### Creating Temporary Shell Environment with Nix

Source: https://context7.com/context7/nixos-and-flakes_thiscute_world/llms.txt

Shows how to enter a temporary shell environment with specific packages using the 'nix shell' command. This is useful for testing or using tools without a global installation. Includes example commands and their expected output.

```bash
# Enter a temporary shell with specific packages
nix shell nixpkgs#hello nixpkgs#cowsay

# Test the packages
hello
# Output: Hello, world!

cowsay "Hello from Nix!"
# Output: ASCII art cow with message

```

--------------------------------

### Interactive Debugging with Nix REPL

Source: https://context7.com/context7/nixos-and-flakes_thiscute_world/llms.txt

Guide to using the Nix REPL for interactive debugging. It covers loading Nixpkgs and flakes, inspecting package metadata, building derivations, and viewing build logs.

```bash
# Load nixpkgs in repl
nix repl -f '<nixpkgs>'
# Or with flakes:
nix repl -f flake:nixpkgs

# Available commands
nix-repl> :?
# :a <expr>     Add attributes to scope
# :b <expr>     Build derivation
# :e <expr>     Open in $EDITOR
# :l <path>     Load Nix expression
# :lf <ref>     Load Nix flake
# :p <expr>     Print recursively
# :t <expr>     Show type
# :doc <expr>   Show documentation
# :log <expr>   Show build logs

# Example: inspect a package
nix-repl> :p pkgs.hello.meta
# Output: { description = "...", homepage = "...", ... }

# Build and test a derivation
nix-repl> :b pkgs.hello
# Builds the package and shows output path

```

--------------------------------

### Configure NixOS System Settings (Nix)

Source: https://nixos-and-flakes.thiscute.world/zh/nixos-with-flakes/get-started-with-nixos

This Nix code snippet configures system settings in `/etc/nixos/configuration.nix`. It includes adding a new user 'ryan' with specified groups, SSH public key, and packages, and enabling the OpenSSH service with specific security settings and firewall rules. This configuration requires the NixOS environment to apply.

```nix
{ config, pkgs, ... }:

{
  imports =
    [ # Include the results of the hardware scan.
      ./hardware-configuration.nix
    ];

  # 省略掉前面的配置......

  # 新增用户 ryan
  users.users.ryan = {
    isNormalUser = true;
    description = "ryan";
    extraGroups = [ "networkmanager" "wheel" ];
    openssh.authorizedKeys.keys = [
        # replace with your own public key
        "ssh-ed25519 <some-public-key> ryan@ryan-pc"
    ];
    packages = with pkgs; [
      firefox
    #  thunderbird
    ];
  };

  # 启用 OpenSSH 后台服务
  services.openssh = {
    enable = true;
    settings = {
      X11Forwarding = true;
      PermitRootLogin = "no"; # disable root login
      PasswordAuthentication = false; # disable password login
    };
    openFirewall = true;
  };

  # 省略其他配置......
}

```

--------------------------------

### Splitting NixOS Configuration with Imports

Source: https://context7.com/context7/nixos-and-flakes_thiscute_world/llms.txt

Demonstrates how to split NixOS system configuration into multiple files using the 'imports' option. This example shows 'configuration.nix' importing hardware, packages, and services modules.

```nix
# configuration.nix
{ config, pkgs, ... }:
{
  imports = [ ./hardware-configuration.nix ./modules/packages.nix ./modules/services.nix ];

  system.stateVersion = "25.05";
}

# modules/packages.nix
{ config, pkgs, ... }:
{
  environment.systemPackages = with pkgs; [
    vim
    git
    curl
  ];
}

```

--------------------------------

### Justfile for NixOS Commands

Source: https://nixos-and-flakes.thiscute.world/zh/best-practices/simplify-nixos-related-commands

This Justfile defines custom commands for managing NixOS configurations with flakes. It simplifies common tasks such as deploying, debugging, updating, and cleaning Nix environments. It requires 'just' to be installed.

```makefile
############################################################################
#
#  Nix commands related to the local machine
#
############################################################################

deploy:
  nixos-rebuild switch --flake . --use-remote-sudo

debug:
  nixos-rebuild switch --flake . --use-remote-sudo --show-trace --verbose

up:
  nix flake update

# Update specific input
# usage: make upp i=home-manager
upp:
  nix flake update $(i)

history:
  nix profile history --profile /nix/var/nix/profiles/system

repl:
  nix repl -f flake:nixpkgs

clean:
  # remove all generations older than 7 days
  sudo nix profile wipe-history --profile /nix/var/nix/profiles/system  --older-than 7d

gc:
  # garbage collect all unused nix store entries
  sudo nix store gc --debug
  sudo nix-collect-garbage --delete-old

############################################################################
#
#  Idols, Commands related to my remote distributed building cluster
#
############################################################################

add-idols-ssh-key:
  ssh-add ~/.ssh/ai-idols

aqua: add-idols-ssh-key
  nixos-rebuild --flake .#aquamarine --target-host aquamarine --build-host aquamarine switch --use-remote-sudo

aqua-debug: add-idols-ssh-key
  nixos-rebuild --flake .#aquamarine --target-host aquamarine --build-host aquamarine switch --use-remote-sudo --show-trace --verbose

ruby: add-idols-ssh-key
  nixos-rebuild --flake .#ruby --target-host ruby --build-host ruby switch --use-remote-sudo

ruby-debug: add-idols-ssh-key
  nixos-rebuild --flake .#ruby --target-host ruby --build-host ruby switch --use-remote-sudo --show-trace --verbose

kana: add-idols-ssh-key
  nixos-rebuild --flake .#kana --target-host kana --build-host kana switch --use-remote-sudo

kana-debug: add-idols-ssh-key
  nixos-rebuild --flake .#kana --target-host kana --build-host kana switch --use-remote-sudo --show-trace --verbose

idols: aqua ruby kana

idols-debug: aqua-debug ruby-debug kana-debug

```

--------------------------------

### Install MinIO Client on NixOS

Source: https://nixos-and-flakes.thiscute.world/nix-store/host-your-own-binary-cache-server

Installs the `minio-client` package on a NixOS system. This client provides `mc` command-line interface for interacting with MinIO and other S3-compatible object storage services. It enables operations like listing, copying, and creating directories.

```nix
{ pkgs, ... }:
{
  environment.systemPackages = with pkgs; [
    minio-client # Alternatives for ls, cp, mkdir, diff, and rsync commands for file systems and object storage
  ];
}
```

--------------------------------

### Node.js Development Environment with flake.nix

Source: https://nixos-and-flakes.thiscute.world/development/intro

This `flake.nix` example defines a development environment using `pkgs.mkShell` that includes Node.js 24, pnpm, and yarn. It specifies the Nixpkgs channel and configures a `shellHook` to print the Node.js version upon entering the environment. This setup allows for seamless use of Node.js tools.

```nix
{
  description = "A Nix-flake-based Node.js development environment";

  inputs = {
    nixpkgs.url = "github:nixos/nixpkgs/nixos-25.05";
  };

  outputs = { self , nixpkgs ,... }:
  let
    # system should match the system you are running on
    system = "x86_64-linux";
  in {
    devShells."${system}".default = let
      pkgs = import nixpkgs { inherit system; };
    in pkgs.mkShell {
      # create an environment with nodejs, pnpm, and yarn
      packages = with pkgs; [
        nodejs_24
        nodePackages.pnpm
        (yarn.override { nodejs = nodejs_24; })
      ];

      shellHook = ''
        echo "node `node --version`"
      '';
    };
  };
}

```

--------------------------------

### Common Use Cases for 'nix run' and 'nix shell'

Source: https://nixos-and-flakes.thiscute.world/zh/other-usage-of-flakes/the-new-cli

Illustrates common practical applications of 'nix run' and 'nix shell', such as temporarily utilizing the 'git' command to clone a configuration repository on a new NixOS host without prior installation. This highlights their utility for bootstrapping and quick access to tools.

```bash
# Using 'nix run' to temporarily use git
nix run nixpkgs#git clone git@github.com:ryan4yin/nix-config.git

# Using 'nix shell' to temporarily enter the git environment
nix shell nixpkgs#git
git clone git@github.com:ryan4yin/nix-config.git
```

--------------------------------

### Nix: Create Executable Dev Environment Wrapper with runCommand

Source: https://nixos-and-flakes.thiscute.world/development/intro

Demonstrates creating a standalone development environment wrapper using `pkgs.runCommand`. This wrapper includes specified packages and an executable entry point (e.g., 'dev-shell') that sets up the environment, allowing it to be run directly or installed system-wide.

```nix
{ description = "A Nix-flake-based Node.js development environment";

  inputs = {
    nixpkgs.url = "github:nixos/nixpkgs/nixos-25.05";
  };

  outputs = { self , nixpkgs ,... }: let
    # system should match the system you are running on
    system = "x86_64-linux";
  in {
    packages."${system}".dev = let
      pkgs = import nixpkgs { inherit system; };
      packages = with pkgs; [ 
          nodejs_22
          nodePackages.pnpm
          nushell
      ];
    in pkgs.runCommand "dev-shell" {
      # Dependencies that should exist in the runtime environment
      buildInputs = packages;
      # Dependencies that should only exist in the build environment
      nativeBuildInputs = [ pkgs.makeWrapper ];
    }
    ''
      mkdir -p $out/bin/
      ln -s ${pkgs.nushell}/bin/nu $out/bin/dev-shell
      wrapProgram $out/bin/dev-shell --prefix PATH : ${pkgs.lib.makeBinPath packages}
    '';
  };
}

```

```nix
{pkgs, lib, ...}নৈতিক{

  environment.systemPackages = [ 
    # Install the wrapper into the system
    (let
      packages = with pkgs; [ 
          nodejs_22
          nodePackages.pnpm
          nushell
      ];
    in pkgs.runCommand "dev-shell" {
      # Dependencies that should exist in the runtime environment
      buildInputs = packages;
      # Dependencies that should only exist in the build environment
      nativeBuildInputs = [ pkgs.makeWrapper ];
    }
    ''
      mkdir -p $out/bin/
      ln -s ${pkgs.nushell}/bin/nu $out/bin/dev-shell
      wrapProgram $out/bin/dev-shell --prefix PATH : ${pkgs.lib.makeBinPath packages}
    '')
  ];
}

```

--------------------------------

### Common Use Case: Cloning Git Repository with `nix run`

Source: https://nixos-and-flakes.thiscute.world/other-usage-of-flakes/the-new-cli

This example shows a practical application of `nix run` for executing a command from a package that might not be installed on the system. It uses `nix run` to execute `git clone` for a specific repository, effectively using Git without a prior system installation.

```bash
nix run nixpkgs#git clone git@github.com:ryan4yin/nix-config.git

```

--------------------------------

### Test Advanced Nix Package after System Rebuild

Source: https://context7.com/context7/nixos-and-flakes_thiscute_world/llms.txt

Command to test the `hello-fancy` package after it has been integrated into the NixOS system configuration. This verifies that the package and its dependencies are correctly installed and executable.

```bash
# callPackage automatically provides dependencies
# Test after rebuild:
hello-fancy
# Output: Colored cow ASCII art with message

```

--------------------------------

### Import and Use Nix Derivation from File

Source: https://nixos-and-flakes.thiscute.world/nixpkgs/callpackage

This example shows how to import a Nix expression from a separate file (`hello.nix`) within the Nix repl, passing the `pkgs` argument as required by the file's definition. It verifies that the imported expression also results in a derivation.

```shell
› cat hello.nix
pkgs:
  pkgs.writeShellScriptBin "hello" '' echo "hello, xxx!" ''

› nix repl -f '<nixpkgs>'
Welcome to Nix 2.13.5. Type :? for help.

warning: Nix search path entry '/nix/var/nix/profiles/per-user/root/channels' does not exist, ignoring
Loading installable ''...
Added 19203 variables.

nix-repl> import ./hello.nix pkgs
«derivation /nix/store/zhgar12vfhbajbchj36vbbl3mg6762s8-hello.drv»
```

--------------------------------

### Verify Nix Derivation in Nix Repl

Source: https://nixos-and-flakes.thiscute.world/nixpkgs/callpackage

This example demonstrates how to verify that a Nix expression results in a derivation when evaluated in the Nix repl. It takes the output of `pkgs.writeShellScriptBin` and shows the resulting derivation path.

```shell
› nix repl -f '<nixpkgs>'
Welcome to Nix 2.13.5. Type :? for help.

Loading installable ''...
Added 19203 variables.

nix-repl> pkgs.writeShellScriptBin "hello" '' echo "hello, xxx!" ''
«derivation /nix/store/zhgar12vfhbajbchj36vbbl3mg6762s8-hello.drv»
```

--------------------------------

### Create Temporary Shell Environment with nix shell

Source: https://nixos-and-flakes.thiscute.world/development/intro

This snippet demonstrates how to use the `nix shell` command to create a temporary development environment with specified packages. It shows an example where `hello` and `cowsay` are not initially available, and then how to enter an environment where they are. This is useful for quickly testing packages.

```shell
# hello is not available
› hello
hello: command not found

# Enter an environment with the 'hello' and `cowsay` package
› nix shell nixpkgs#hello nixpkgs#cowsay

# hello is now available
› hello
Hello, world!

# ponysay is also available
› cowsay "Hello, world!"
 _______ 
< hello >
 ------- 
        \   ^__^
         \  (oo)\л_______
            (__)\       )\/ 
                ||----w |
                ||     ||

```

--------------------------------

### Nix Module Importing and Configuring 'foo'

Source: https://nixos-and-flakes.thiscute.world/other-usage-of-flakes/module-system

Demonstrates how to import the 'foo.nix' module and configure its options within another Nix file. This example shows setting the enable flag, specifying a package, and providing custom configuration for the 'foo' program.

```nix
# ./bar.nix
{ config, lib, pkgs, ... }:

{
  imports = [
    ./foo.nix
  ];

  programs.foo ={
    enable = true;
    package = pkgs.hello;
    extraConfig = ''
      foo baz
    '';
  };
}
```

--------------------------------

### Directory Structure for NixOS Docker Modules

Source: https://nixos-and-flakes.thiscute.world/other-usage-of-flakes/module-system

This example shows a potential directory structure for organizing NixOS module configurations related to Docker. It demonstrates how to split configurations into distinct files, with some importing others to build upon a base configuration.

```bash
.\n├── docker-default.nix  # Basic Docker configuration, including starting at boot
├── docker-btrfs.nix    # Imports docker-default.nix and changes the storage driver to btrfs
├── docker-china.nix    # Imports docker-default.nix and sets a domestic mirror
└── docker-proxy.nix    # Imports docker-default.nix and sets an HTTP proxy

```

--------------------------------

### Nixpkgs Module Structure Example

Source: https://nixos-and-flakes.thiscute.world/zh/nixos-with-flakes/nixos-flake-and-module-system

A simplified representation of a Nixpkgs module. Modules are Nix functions that accept specific arguments and can import other modules. They define configuration options and can be used to build modular NixOS configurations.

```nix
{lib, config, options, pkgs, ...}:
{
  # Import other Modules
  imports = [
    # ......
    # ./xxx.nix
  ];

  for.bar.enable = true;
  # other options declarations
  # ...
}
```

--------------------------------

### Nix Development Environment Setup with pkgs.mkShell

Source: https://nixos-and-flakes.thiscute.world/development/intro

This is the source code for `pkgs.mkShell`, a Nix function used to define development environments. It explains how to use parameters like `name`, `packages`, `buildInputs`, and `shellHook` to configure the environment. This derivation is intended for consumption by `nix-shell` or `nix develop`.

```nix
{ lib, stdenv, buildEnv }:

# A special kind of derivation that is only meant to be consumed by the
# nix-shell.
{ name ? "nix-shell"
, # a list of packages to add to the shell environment
  packages ? [ ]
, # propagate all the inputs from the given derivations
  inputsFrom ? [ ]
, buildInputs ? [ ]
, nativeBuildInputs ? [ ]
, propagatedBuildInputs ? [ ]
, propagatedNativeBuildInputs ? [ ]
, ...
}@attrs:
let
  mergeInputs = name:
    (attrs.${name} or [ ]) ++ 
    (lib.subtractLists inputsFrom (lib.flatten (lib.catAttrs name inputsFrom)));

  rest = builtins.removeAttrs attrs [
    "name"
    "packages"
    "inputsFrom"
    "buildInputs"
    "nativeBuildInputs"
    "propagatedBuildInputs"
    "propagatedNativeBuildInputs"
    "shellHook"
  ];
in

stdenv.mkDerivation ({
  inherit name;

  buildInputs = mergeInputs "buildInputs";
  nativeBuildInputs = packages ++ (mergeInputs "nativeBuildInputs");
  propagatedBuildInputs = mergeInputs "propagatedBuildInputs";
  propagatedNativeBuildInputs = mergeInputs "propagatedNativeBuildInputs";

  shellHook = lib.concatStringsSep "\n" (lib.catAttrs "shellHook"
    (lib.reverseList inputsFrom ++ [ attrs ]));

  phases = [ "buildPhase" ];

  # ......

  # when distributed building is enabled, prefer to build locally
  preferLocalBuild = true;
} // rest)

```

--------------------------------

### Nix Development Environment Configuration Example

Source: https://nixos-and-flakes.thiscute.world/faq

This Nix configuration snippet demonstrates how to define packages for a development environment, specifically including a custom Python environment with several packages. It's intended for use within NixOS or Home Manager configurations.

```nix
{
   # as a nixos module
   # environment.systemPackages = with pkgs; [
   #
   # or as a home manager module
   home.packages = with pkgs; [
     lldb

     (python311.withPackages (ps:
       with ps; [
         ipython
         pandas
         requests
         pyquery
         pyyaml
       ]
     ))
   ];
}
```

--------------------------------

### Basic Nix Module Structure

Source: https://nixos-and-flakes.thiscute.world/nixos-with-flakes/modularize-the-configuration

A fundamental example of a Nix module's structure. This snippet defines a partial configuration that can be imported by other Nix modules. It typically receives `config` and `pkgs` as arguments to access system configurations and packages.

```nix
{ config, pkgs, ...}:
{
  # Configuration stuff ...
}
```

--------------------------------

### Show Detailed Error Messages with nixos-rebuild

Source: https://nixos-and-flakes.thiscute.world/best-practices/debugging

Append flags like `--show-trace`, `--print-build-logs`, and `--verbose` to `nixos-rebuild` to get more informative error messages during deployment. A concise version `-L -v` is also available.

```bash
cd /etc/nixos
sudo nixos-rebuild switch --flake .#myhost --show-trace --print-build-logs --verbose
```

```bash
sudo nixos-rebuild switch --flake .#myhost --show-trace -L -v
```

--------------------------------

### Enable NixOS Flakes Support

Source: https://nixos-and-flakes.thiscute.world/zh/nixos-with-flakes/nixos-with-flakes-enabled

Enables experimental Flakes features and the new Nix command-line tool by modifying `/etc/nixos/configuration.nix`. It also installs necessary packages like git and sets the default editor to vim. This configuration requires NixOS 22.11 or newer.

```nix
{ config, pkgs, ... }:

{
  imports =
    [ # Include the results of the hardware scan.
      ./hardware-configuration.nix
    ];

  # ...... 

  # 启用 Flakes 特性以及配套的船新 nix 命令行工具
  nix.settings.experimental-features = [ "nix-command" "flakes" ];
  environment.systemPackages = with pkgs; [ 
    # Flakes 通过 git 命令拉取其依赖项，所以必须先安装好 git
    git
    vim
    wget
  ];
  # 将默认编辑器设置为 vim
  environment.variables.EDITOR = "vim";

  # ...... 
}

```

--------------------------------

### Bash Scripting: Evaluating Merged NixOS Configurations

Source: https://nixos-and-flakes.thiscute.world/nixos-with-flakes/modularize-the-configuration

Bash commands to evaluate specific configuration options from a NixOS Flake using `nix eval`. These examples demonstrate how `lib.mkBefore` and `lib.mkAfter` affect the final merged output for multiline strings, single-line strings, and lists.

```bash
# Example 1: multiline string merging
› echo $(nix eval .#nixosConfigurations.my-nixos.config.programs.bash.shellInit)

# example 2: single-line string merging
› echo $(nix eval .#nixosConfigurations.my-nixos.config.programs.zsh.shellInit)

# Example 3: list merging
› nix eval .#nixosConfigurations.my-nixos.config.nix.settings.substituters
```

--------------------------------

### Basic NixOS Configuration with Nix Flakes

Source: https://context7.com/context7/nixos-and-flakes_thiscute_world/llms.txt

Defines a basic NixOS configuration using Nix Flakes. It specifies the Nixpkgs channel and sets up a system configuration for 'myhost'. This file serves as the entry point for NixOS deployments.

```nix
{ description = "NixOS configuration with Flakes";

  inputs = {
    nixpkgs.url = "github:nixos/nixpkgs/nixos-25.05";
  };

  outputs = { self, nixpkgs, ... }:
    {
      nixosConfigurations.myhost = nixpkgs.lib.nixosSystem {
        system = "x86_64-linux";
        modules = [ ./configuration.nix ];
      };
    };
}

```

--------------------------------

### 生成随机密码

Source: https://nixos-and-flakes.thiscute.world/zh/nix-store/host-your-own-binary-cache-server

使用 Nix 包管理器运行 `pwgen` 命令来生成一个随机的、安全的密码，常用于 S3 访问密钥或用户凭据。

```bash
nix run nixpkgs#pwgen -- -c -n -y -s -B 32 1
# => oenu1Yuch3rohz2ahveid0koo4giecho
```

--------------------------------

### 将路径复制到 S3 二进制缓存

Source: https://nixos-and-flakes.thiscute.world/zh/nix-store/host-your-own-binary-cache-server

使用 `nix copy` 命令将本地签名后的 Nix Store 路径复制到 S3 二进制缓存中。通过 `to` 参数指定 S3 目标，包括配置文件（profile）和端点（endpoint）。

```bash
nix copy --to 's3://nix-cache?profile=nixbuilder&endpoint=s3.homelab.local' /run/current-system
```

--------------------------------

### Initialize Nix Flake and Display flake.nix

Source: https://nixos-and-flakes.thiscute.world/zh/nixos-with-flakes/nixos-with-flakes-enabled

Initializes a new Nix Flake project using the 'full' template and then displays the generated `flake.nix` file. This is useful for understanding the structure of a comprehensive flake configuration.

```bash
nix flake init -t templates#full
cat flake.nix

```

--------------------------------

### Run Nix Package Directly using `nix run`

Source: https://nixos-and-flakes.thiscute.world/other-usage-of-flakes/the-new-cli

The `nix run` command creates an environment for a specified Nix package and directly executes its primary program. The package is not installed into the system environment. This is useful for executing single commands or programs provided by a Nix package without a persistent installation.

```shell
› nix run nixpkgs#hello
Hello, world!

```

--------------------------------

### 配置 Nix 使用 S3 二进制缓存

Source: https://nixos-and-flakes.thiscute.world/zh/nix-store/host-your-own-binary-cache-server

在 NixOS 配置文件 (`configuration.nix` 或自定义模块) 中，通过 `nix.settings.extra-substituters` 添加 S3 缓存的 URL，并通过 `nix.settings.extra-trusted-public-keys` 添加对应的公钥，以启用 S3 二进制缓存。

```nix
{
  nix = {
    settings = {
      extra-substituters = [
        "https://s3.homelab.local/nix-cache/"
      ];
      extra-trusted-public-keys = [
        "s3.homelab.local-1:m0J/oDlLEuG6ezc6MzmpLCN2MYjssO3NMIlr9JdxkTs="
      ];
    };
  };
}
```

--------------------------------

### Overriding Default Nixpkgs Option with lib.mkForce

Source: https://nixos-and-flakes.thiscute.world/nixos-with-flakes/modularize-the-configuration

This Nix code example shows how to override a default value set by `lib.mkDefault` using `lib.mkForce` in a more specific NixOS module (e.g., `core-desktop.nix`). `lib.mkForce` has a higher priority (lower number, 50) than `lib.mkDefault` (1000), ensuring the forced value takes precedence. This example overrides `nixpkgs.config.allowUnfree` to `true`.

```nix
{ lib, pkgs, ... }:

{
  # import the base module
  imports = [
    ./core-server.nix
  ];

  # override the default value defined in the base module
  nixpkgs.config.allowUnfree = lib.mkForce true;

  # ...... 
}

```

--------------------------------

### Enter Nix Build Environment for Packages

Source: https://context7.com/context7/nixos-and-flakes_thiscute_world/llms.txt

Demonstrates how to enter the build environment of a specific package using `nix develop`. This provides access to build dependencies and development tools, allowing for manual execution of build phases.

```bash
# Enter the build environment of the 'hello' package
nix develop nixpkgs#hello

# All build dependencies and tools are now available
env | grep CXX
# Output: CXX=g++

c++ --version
# Output: g++ (GCC) 12.3.0

# Execute build phases manually
cd /tmp/build
unpackPhase  # Unpacks source
configurePhase  # Runs ./configure
buildPhase  # Compiles the package
./hello  # Run the built binary
# Output: Hello, world!

```

--------------------------------

### Override stdenv.mkDerivation Internal Parameters

Source: https://nixos-and-flakes.thiscute.world/zh/nixpkgs/overriding

This example demonstrates overriding internal parameters of `stdenv.mkDerivation` using `overrideAttrs`. It specifically shows setting `separateDebugInfo` to `true` for the `pkgs.hello` package.

```nix
helloWithDebug = pkgs.hello.overrideAttrs (finalAttrs: previousAttrs: {
    separateDebugInfo = true;
});
```

--------------------------------

### Override Derivation Attributes with overrideAttrs

Source: https://nixos-and-flakes.thiscute.world/zh/nixpkgs/overriding

This example illustrates how to use `overrideAttrs` to modify attributes of a derivation built with `stdenv.mkDerivation`. It shows overriding the `doCheck` attribute for the `pkgs.hello` package.

```nix
helloWithDebug = pkgs.hello.overrideAttrs (finalAttrs: previousAttrs: {
    doCheck = false;
});
```

--------------------------------

### 查看 NixOS 中 Bash 的路径和符号链接

Source: https://nixos-and-flakes.thiscute.world/zh/nix-store/intro

此命令演示了如何在 NixOS 环境中查找 `bash` 命令，并显示其在 Nix Store 中的具体路径以及 `/run/current-system/sw/bin/bash` 的符号链接指向。这有助于理解 NixOS 如何通过软链接提供软件包。

```bash
# 查看环境中的 bash 来自哪个路径（使用 NixOS 安装）
› which bash
╭───┬─────────┬─────────────────────────────────┬──────────╮
│ # │ command │              path               │   type   │
├───┼─────────┼─────────────────────────────────┼──────────┤
│ 0 │ bash    │ /run/current-system/sw/bin/bash │ external │
╰───┴─────────┴─────────────────────────────────┴──────────╯

› ls -al /run/current-system/sw/bin/bash
lrwxrwxrwx 15 root root 76 1970年 1月 1日 /run/current-system/sw/bin/bash -> /nix/store/1zslabm02hi75anb2w8zjrqwzgs0vrs3-bash-interactive-5.2p26/bin/bash
```

--------------------------------

### Nix Module for Conditional Import Example

Source: https://nixos-and-flakes.thiscute.world/other-usage-of-flakes/module-system

A simple Nix module file (`foo.nix`) intended to be conditionally imported into a NixOS configuration. This module defines a `warnings` attribute.

```nix
{ warnings = ["foo"];}
```

--------------------------------

### Override Nix Package Parameters

Source: https://nixos-and-flakes.thiscute.world/zh/nixpkgs/overriding

This example demonstrates how to override specific parameters of a Nix package, such as `rimeDataPkgs` for `fcitx5-rime`. It returns a new derivation with the specified parameters changed while retaining others.

```nix
pkgs.fcitx5-rime.override {
    rimeDataPkgs = [
        ./rime-data-flypy
    ];
}
```

--------------------------------

### 查看 home-manager 中 Cowsay 的路径和符号链接

Source: https://nixos-and-flakes.thiscute.world/zh/nix-store/intro

此命令演示了如何使用 `which` 和 `ls -al` 命令查找通过 home-manager 安装的 `cowsay` 命令，并显示其在 Nix Store 中的具体路径以及 `/etc/profiles/per-user/ryan/bin/cowsay` 的符号链接指向。这有助于理解 home-manager 如何为用户管理软件包。

```bash
# 查看环境中的 cowsay 来自哪个路径（使用 home-manager 安装）
› which cowsay
╭───┬─────────┬────────────────────────────────────────┬──────────╮
│ # │ command │                  path                  │   type   │
├───┼─────────┼────────────────────────────────────────┼──────────┤
│ 0 │ cowsay  │ /etc/profiles/per-user/ryan/bin/cowsay │ external │
╰───┴─────────┴────────────────────────────────────────┴──────────╯

› ls -al /etc/profiles/per-user/ryan/bin/cowsay
lrwxrwxrwx 2 root root 72 1970年 1月 1日 /etc/profiles/per-user/ryan/bin/cowsay -> /nix/store/w2czyf82gxz4vy9kzsdhr88112bmc0c1-home-manager-path/bin/cowsay
```

--------------------------------

### NixOS Module Definition (foo.nix)

Source: https://nixos-and-flakes.thiscute.world/zh/other-usage-of-flakes/module-system

A simple NixOS module file that defines a 'warnings' attribute with a list of strings. This module is intended to be conditionally imported by other configurations, such as the example flake.nix.

```nix
{ warnings = ["foo"];}

```

--------------------------------

### Basic NixOS Flake Configuration

Source: https://nixos-and-flakes.thiscute.world/zh/nixos-with-flakes/nixos-with-flakes-enabled

Defines a simple NixOS Flake configuration. It specifies the NixOS channel to use and sets up a NixOS configuration for a specific hostname, importing the existing `configuration.nix`. This serves as a minimal entry point for managing NixOS with Flakes.

```nix
{ 
  description = "A simple NixOS flake";

  inputs = {
    # NixOS 官方软件源，这里使用 nixos-25.05 分支
    nixpkgs.url = "github:NixOS/nixpkgs/nixos-25.05";
  };

  outputs = { self, nixpkgs, ... }@inputs: {
    # TODO 请将下面的 my-nixos 替换成你的 hostname
    nixosConfigurations.my-nixos = nixpkgs.lib.nixosSystem {
      modules = [
        # 这里导入之前我们使用的 configuration.nix，
        # 这样旧的配置文件仍然能生效
        ./configuration.nix
      ];
    };
  };
}

```

--------------------------------

### Show Nix Flake Templates

Source: https://nixos-and-flakes.thiscute.world/zh/nixos-with-flakes/nixos-with-flakes-enabled

Lists available official templates for creating Nix Flakes. This command helps users discover pre-defined structures for different NixOS configurations.

```bash
nix flake show templates

```

--------------------------------

### Deploy NixOS System Configuration

Source: https://context7.com/context7/nixos-and-flakes_thiscute_world/llms.txt

Commands for deploying NixOS system configurations using flakes, including options for detailed logging and tracing. It also covers listing system generations and performing rollbacks.

```bash
# Deploy NixOS configuration with detailed logging
cd /etc/nixos
sudo nixos-rebuild switch --flake .#myhost --show-trace -L -v

# List previous system generations
sudo nix-env --list-generations --profile /nix/var/nix/profiles/system

# Rollback to previous generation
sudo nixos-rebuild switch --rollback

# Boot into a specific generation (shown in GRUB menu)
# NixOS automatically adds all generations to bootloader

```

--------------------------------

### 使用 nix develop 后的 PATH 环境变量

Source: https://nixos-and-flakes.thiscute.world/zh/nix-store/intro

此命令演示了在项目仓库中执行 `nix develop` 命令后，`PATH` 环境变量的内容。可以看到，`nix develop` 将多个 Nix Store 中的软件包路径添加到了 `PATH` 中，使得这些软件包在当前 shell 环境中立即可用。

```bash
› nix develop
node v22.18.0

› env | egrep '^PATH'
PATH=/nix/store/v0sf67x7sw6pg277amhgf3j84m60wrqn-pre-commit-4.2.0/bin:/nix/store/yva1rk7v7s31dpwkwxcphpqkn5l3bp1f-nodejs-22.18.0-dev/bin:/nix/store/vrqcpwq576gar2i430lj91v37b7k8jw2-nodejs-22.18.0/bin:/nix/store/qzw56f9vai5jg9dm3wbm45r6cc6b65d8-pnpm-10.15.0/bin:/nix/store/n8b4js8xkj12d1jjjqm86p9lwmyhh2rf-yarn-1.22.22/bin:/nix/store/bjhv861k4ri85l1vyrnr954ncsdbw3ri-prettier-3.5.3/bin:/nix/store/m6zld27lmw422ca5zywhkq8kmlaf8inh-git-2.50.1/bin:/nix/store/gz3wn2d2xbl758jsln65za95mdc9yial-typos-1.32.0/bin:/nix/store/bx0wnjpp6mgr6bmh5q1mz9c1ach34lbn-nixfmt-0.6.0-bin/bin:/nix/store/zf4jj08zh07zg1j2s64g8sfjbzfq70lm-pandoc-cli-3.6/bin:/nix/store/g7i75czfbw9sy5f8v7rjbama6lr3ya3s-patchelf-0.15.0/bin:/nix/store/kaj8d1zcn149m40s9h0xi0khakibiphz-gcc-wrapper-14.3.0/bin:/nix/store/8adzgnxs3s0pbj22qhk9zjxi1fqmz3xv-gcc-14.3.0/bin:/nix/store/p2ixvjsas4qw58dcwk01d22skwq4fyka-glibc-2.40-66-bin/bin:/nix/store/rry6qingvsrqmc7ll7jgaqpybcbdgf5v-coreutils-9.7/bin:/nix/store/87zpmcmwvn48z4lbrfba74b312h22s6c-binutils-wrapper-2.44/bin:/nix/store/ap35np2bkwaba3rxs3qlxpma57n2awyb-binutils-2.44/bin:/nix/store/rry6qingvsrqmc7ll7jgaqpybcbdgf5v-coreutils-9.7/bin:/nix/store/392hs9nhm6wfw4imjllbvb1wil1n39qx-findutils-4.10.0/bin:/nix/store/xw0mf3shymq3k7zlncf09rm8917sdi4h-diffutils-3.12/bin:/nix/store/4rpiqv9yr2pw5094v4wc33ijkqjpm9sa-gnused-4.9/bin:/nix/store/l2wvwyg680h0v2la18hz3yiznxy2naqw-gnugrep-3.11/bin:/nix/store/c1z5j28ndxljf1ihqzag57bwpfpzms0g-gawk-5.3.2/bin:/nix/store/w60s4xh1pjg6dwbw7j0b4xzlpp88q5qg-gnutar-1.35/bin:/nix/store/xd9m9jkvrs8pbxvmkzkwviql33rd090j-gzip-1.14/bin:/nix/store/w1pxx760yidi7n9vbi5bhpii9xxl5vdj-bzip2-1.0.8-bin/bin:/nix/store/xk0d14zpm0njxzdm182dd722aqhav2cc-gnumake-4.4.1/bin:/nix/store/cfqbabpc7xwg8akbcchqbq3cai6qq2vs-bash-5.2p37/bin:/nix/store/gj54zvf7vxll1mzzmqhqi1p4jiws3mfb-patch-2.7.6/bin:/nix/store/22rpb6790f346c55iqi6s9drr5qgmyjf-xz-5.8.1-bin/bin:/nix/store/xlmpcglsq8l09qh03rf0virz0331pjdc-file-5.45/bin:/home/ryan/.local/bin:/run/wrappers/bin:/etc/profiles/per-user/ryan/bin:/nix/var/nix/profiles/default/bin:/run/current-system/sw/bin:/home/ryan/go/bin:/home/ryan/.cargo/bin:/home/ryan/.npm/bin:/home/ryan/.local/bin:/home/ryan/go/bin:/home/ryan/.cargo/bin:/home/ryan/.npm/bin
```

--------------------------------

### Rebuild NixOS System

Source: https://nixos-and-flakes.thiscute.world/nix-store/host-your-own-binary-cache-server

Rebuilds the NixOS system to apply the new configuration, including the S3 binary cache settings. This command ensures that the system is updated and starts utilizing the configured substituter.

```bash
sudo nixos-rebuild switch --upgrade --flake .#<HOST>
```

--------------------------------

### Execute Nix package build phases: unpack, configure, build

Source: https://nixos-and-flakes.thiscute.world/development/intro

Demonstrates executing individual build phases (`unpackPhase`, `configurePhase`, `buildPhase`) for the 'hello' package within its Nix development environment. This is useful for debugging build processes or running specific commands within the package's build context.

```shell
# unpack source code
› unpackPhase
unpacking source archive /nix/store/pa10z4ngm0g83kx9mssrqzz30s84vq7k-hello-2.12.1.tar.gz
source root is hello-2.12.1
setting SOURCE_DATE_EPOCH to timestamp 1653865426 of file hello-2.12.1/ChangeLog

› ls
hello-2.12.1

› cd hello-2.12.1/

# generate Makefile
› configurePhase
configure flags: --prefix=/tmp/xxx/outputs/out --prefix=/tmp/xxx/outputs/out
checking for a BSD-compatible install... /nix/store/02dr9ymdqpkb75vf0v1z2l91z2q3izy9-coreutils-9.3/bin/install -c
checking whether build environment is sane... yes
checking for a thread-safe mkdir -p... /nix/store/02dr9ymdqpkb75vf0v1z2l91z2q3izy9-coreutils-9.3/bin/mkdir -p
checking for gawk... gawk
checking whether make sets $(MAKE)... yes
checking whether make supports nested variables... yes
checking for gcc... gcc
# ......
configure: creating ./config.status
config.status: creating Makefile
config.status: creating po/Makefile.in
config.status: creating config.h
config.status: config.h is unchanged
config.status: executing depfiles commands
config.status: executing po-directories commands
config.status: creating po/POTFILES
config.status: creating po/Makefile

# build the package
› buildPhase
build flags: SHELL=/run/current-system/sw/bin/bash
make  all-recursive
make[1]: Entering directory '/tmp/xxx/hello-2.12.1'
# ......
ranlib lib/libhello.a
gcc  -g -O2   -o hello src/hello.o  ./lib/libhello.a
make[2]: Leaving directory '/tmp/xxx/hello-2.12.1'
make[1]: Leaving directory '/tmp/xxx/hello-2.12.1'

# run the built program
› ./hello
Hello, world!
```

--------------------------------

### Nix Package Collision Example

Source: https://context7.com/context7/nixos-and-flakes_thiscute_world/llms.txt

Illustrates a common Nix error scenario: package collisions, where different packages may conflict due to shared files or dependencies, such as `lldb` and `python311` both containing `six.py`.

```nix
# Problem: collision between packages with different library versions
# Error: collision between `lldb` and `python311` due to `six.py`


```
Tokens:
Raw