Nix Container Image

The official NixOS Nix container image, wrapped for use in Nix builds with reproducible hashing and content addressing.

Image Details

Image

string

docker.io/nixos/nix:2.34.0

Digest

string

sha256:b9c9611c8530fa8049a1215b20638536e1e71dcaf85212e47845112caf3adeea

Nix Hash

string

sha256-3t6p1wzOWhcWQZvfbkTqWJtCj64XIwmGbnfXL4JzsdQ=

Architecture

string

linux/amd64

Version

string

2.34.0

Source Configuration

The image is defined in /images/nix/default.nix:

images/nix/default.nix

{ pkgs }:
let
  image = "docker.io/nixos/nix:2.34.0@sha256:b9c9611c8530fa8049a1215b20638536e1e71dcaf85212e47845112caf3adeea";
  parts = builtins.match "(.+/)(.+):(.+)@(.+)" image;
in
(pkgs.dockerTools.pullImage {
  imageName = builtins.elemAt parts 0 + builtins.elemAt parts 1;
  finalImageName = builtins.elemAt parts 1;
  finalImageTag = builtins.elemAt parts 2;
  imageDigest = builtins.elemAt parts 3;
  hash = "sha256-3t6p1wzOWhcWQZvfbkTqWJtCj64XIwmGbnfXL4JzsdQ=";
  os = "linux";
  arch = "amd64";
}).overrideAttrs
  {
    __structuredAttrs = true;
    unsafeDiscardReferences.out = true;
  }

Usage

In a Nix Flake

Reference the Nix image in your flake:

flake.nix

{
  inputs = {
    nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable";
    nur-nix.url = "github:yourusername/nur-nix";
  };

  outputs = { self, nixpkgs, nur-nix }: {
    packages.x86_64-linux.nix-container = 
      nur-nix.images.x86_64-linux.nix;
  };
}

Build and Load

Build the image and load it into Docker or Podman:

# Build the image
nix build github:yourusername/nur-nix#images.x86_64-linux.nix

# Load into Docker
docker load < result

# Run the container
docker run --rm nixos/nix:2.34.0 nix --version

Direct Usage

Use the image directly without a flake:

# Build from local checkout
nix build .#images.x86_64-linux.nix

# Or with nix-build
nix-build -A images.nix

Common Use Cases

CI/CD Builds

Use Nix in containerized CI/CD pipelines:

.github/workflows/build.yml

jobs:
  build:
    runs-on: ubuntu-latest
    container:
      image: nixos/nix:2.34.0
    steps:
      - uses: actions/checkout@v4
      - name: Build with Nix
        run: nix build

Reproducible Builds

Build Nix expressions in a clean, reproducible environment:

docker run --rm -v $(pwd):/workspace \
  -w /workspace \
  nixos/nix:2.34.0 \
  nix build --experimental-features "nix-command flakes"

Development Environment

Run a Nix development shell in a container:

docker run -it --rm -v $(pwd):/workspace \
  -w /workspace \
  nixos/nix:2.34.0 \
  nix develop

Package Testing

Test Nix packages in isolation:

docker run --rm nixos/nix:2.34.0 \
  nix-shell -p hello --run "hello"

CI/CD Integration

GitHub Actions

Use the Nix image in GitHub Actions workflows:

.github/workflows/nix-build.yml

name: Nix Build

on: [push, pull_request]

jobs:
  build:
    runs-on: ubuntu-latest
    container:
      image: nixos/nix:2.34.0
      options: --user root
    
    steps:
      - uses: actions/checkout@v4
      
      - name: Configure Nix
        run: |
          mkdir -p ~/.config/nix
          echo "experimental-features = nix-command flakes" > ~/.config/nix/nix.conf
      
      - name: Build
        run: nix build
      
      - name: Run checks
        run: nix flake check

GitLab CI

Use the Nix image in GitLab CI pipelines:

.gitlab-ci.yml

image: nixos/nix:2.34.0

before_script:
  - mkdir -p ~/.config/nix
  - echo "experimental-features = nix-command flakes" > ~/.config/nix/nix.conf

build:
  script:
    - nix build
    - nix flake check

In NixOS Configuration

Use the Nix image in a NixOS container configuration:

configuration.nix

{ config, pkgs, nur-nix, ... }:

{
  virtualisation.oci-containers.containers.nix-builder = {
    imageFile = nur-nix.images.x86_64-linux.nix;
    image = "nixos/nix:2.34.0";
    volumes = [
      "/nix:/nix"
      "/tmp:/tmp"
    ];
    extraOptions = [
      "--privileged"
    ];
  };
}

Running Nix in a container may require privileged access for certain operations. Use --privileged cautiously and only when necessary.

Configuration

Enabling Flakes

The container doesn’t have flakes enabled by default. Enable them:

# Create config directory
docker run --rm nixos/nix:2.34.0 sh -c '
  mkdir -p ~/.config/nix && \
  echo "experimental-features = nix-command flakes" > ~/.config/nix/nix.conf
'

Or mount a config file:

# Create nix.conf locally
echo "experimental-features = nix-command flakes" > nix.conf

# Mount it into the container
docker run --rm \
  -v $(pwd)/nix.conf:/etc/nix/nix.conf \
  nixos/nix:2.34.0 \
  nix flake show

Binary Cache Configuration

Configure trusted binary caches:

nix.conf

experimental-features = nix-command flakes
substituters = https://cache.nixos.org https://cache.example.com
trusted-public-keys = cache.nixos.org-1:6NCHdD59X431o0gWypbMrAURkbJ16ZPMQFGspcDShjY=

Mount the config:

docker run --rm \
  -v $(pwd)/nix.conf:/etc/nix/nix.conf \
  nixos/nix:2.34.0 \
  nix build

Advanced Usage

Multi-Stage Builds

Use the Nix image in multi-stage Docker builds:

Dockerfile

FROM nixos/nix:2.34.0 AS builder

WORKDIR /app
COPY . .

RUN nix build --experimental-features "nix-command flakes"

FROM alpine:latest
COPY --from=builder /app/result /app
CMD ["/app/bin/myapp"]

Remote Builds

Use the container as a remote builder:

# On your local machine
nix build \
  --builders "ssh://user@remote-host x86_64-linux" \
  --max-jobs 4

Share the Nix store between container runs:

# Create a named volume for the Nix store
docker volume create nix-store

# Use it in your containers
docker run --rm \
  -v nix-store:/nix \
  nixos/nix:2.34.0 \
  nix-shell -p hello --run hello

Sharing the Nix store can significantly speed up subsequent builds by reusing previously built derivations.

Troubleshooting

Permission Errors

If you encounter permission errors accessing /nix:

# Run as root in the container
docker run --rm --user root nixos/nix:2.34.0 nix build

# Or fix permissions on volume
docker run --rm --user root -v nix-store:/nix alpine chown -R 1000:1000 /nix

Flakes Not Working

If flakes commands fail, ensure experimental features are enabled:

docker run --rm nixos/nix:2.34.0 sh -c '
  mkdir -p ~/.config/nix && \
  echo "experimental-features = nix-command flakes" > ~/.config/nix/nix.conf && \
  nix flake show
'

Hash Mismatch

If you encounter a hash mismatch error:

Update the digest in the source file
Run the build to get the new hash
Update the hash field with the new value

nix build .#images.x86_64-linux.nix 2>&1 | grep "got:"

Sandbox Issues

Some Nix operations require sandbox to be disabled:

docker run --rm \
  -e NIX_CONFIG="sandbox = false" \
  nixos/nix:2.34.0 \
  nix build

Version Information

This image uses Nix 2.34.0, which includes improved flakes support, better error messages, and performance enhancements.

Key features in Nix 2.34.0:

Improved flakes stability
Better content-addressed derivations
Enhanced store path verification
Updated CLI with better UX

Next Steps

FFmpeg Image

Explore the FFmpeg container image

Images Overview

Back to images overview

Container Images

Nix Container Image

Image Details

Source Configuration

Usage

In a Nix Flake

Build and Load

Direct Usage

Common Use Cases

CI/CD Integration

GitHub Actions

GitLab CI

In NixOS Configuration

Configuration

Enabling Flakes

Binary Cache Configuration

Advanced Usage

Multi-Stage Builds

Remote Builds

Troubleshooting

Version Information

Next Steps

FFmpeg Image

Images Overview

Build docs developers (and LLMs) love

Container Images

​Image Details

​Source Configuration

​Usage

​In a Nix Flake

​Build and Load

​Direct Usage

​Common Use Cases

​CI/CD Integration

​GitHub Actions

​GitLab CI

​In NixOS Configuration

​Configuration

​Enabling Flakes

​Binary Cache Configuration

​Advanced Usage

​Multi-Stage Builds

​Remote Builds

​Nix Store Sharing

​Troubleshooting

​Version Information

​Next Steps

FFmpeg Image

Images Overview

Build docs developers (and LLMs) love

Image Details

Source Configuration

Usage

In a Nix Flake

Build and Load

Direct Usage

Common Use Cases

CI/CD Integration

GitHub Actions

GitLab CI

In NixOS Configuration

Configuration

Enabling Flakes

Binary Cache Configuration

Advanced Usage

Multi-Stage Builds

Remote Builds

Nix Store Sharing

Troubleshooting

Version Information

Next Steps