docker2nix

README

docker2nix

Convert Dockerfiles to Nix expressions for nixpkgs dockerTools or nix2container.

[!WARNING] Very WIP and, at this point, mostly vibed

Usage

# From stdin
cat Dockerfile | docker2nix

# From file
docker2nix ./Dockerfile

# nix2container output
docker2nix --format nix2container ./Dockerfile

Formats

Flag value	Output function
docker-tools (default)	dockerTools.buildLayeredImage { ... }
nix2container	nix2container.buildImage { ... }

Example

Input:

FROM ubuntu:24.04
ENV FOO=bar
CMD ["/app/main"]

Output (docker-tools):

dockerTools.buildLayeredImage {
  name = "ubuntu";
  tag = "24.04";
  config = {
    Env = [
      "FOO=bar";
    ];
    Cmd = [
      "/app/main";
    ];
  };
}

Multi-stage Dockerfiles are supported. Named stages become let bindings in the output.

RUN instructions (nix2container)

nix2container is intentionally designed around Nix derivations, not imperative shell commands. It has no equivalent of runAsRoot in dockerTools.buildLayeredImage. Each RUN instruction is approximated as a nix2container.buildLayer wrapping a pkgs.runCommand, one layer per instruction to match Docker's layering model.

[!WARNING] Manual translation to Nix derivations is required for most real RUN commands.

Installation

nix build github:UnstoppableMango/docker2nix

Or run directly:

nix run github:UnstoppableMango/docker2nix -- ./Dockerfile

Development

Requires Nix with flakes enabled. With direnv:

direnv allow

Or manually:

nix develop

Commands

# Build
nix build .#

# Test
ginkgo run -r

# Format
nix fmt

# Lint
nix flake check

# Regenerate protobuf
buf generate

# Sync go.sum + nix/gomod2nix.toml
make tidy

Supported Dockerfile Instructions

Instruction	Status
FROM	Supported
ENV	Supported
CMD	Supported
RUN	Supported
COPY	Parsed, not yet rendered
Multi-stage (AS)	Supported

License

See LICENSE.

Documentation

Overview

Package main is the entry point for the docker2nix CLI.