Nixpacks

Overview

Nixpacks takes a source directory and produces an OCI image: a provider detects the language, proposes Nix packages plus install, build and start commands, and Nixpacks generates a Dockerfile and builds it with Docker BuildKit. It was created by Railway and is still offered as a builder by self-hosted platforms such as Coolify and Dokploy.

Status: maintenance mode. Since September 2025 the README states that Nixpacks is not under active development and recommends Railpack as the replacement. The last release is v1.41.0 (October 2025). Existing builds keep working, but language versions are frozen at what that release knows (Node up to 24, Python up to 3.13, Go up to 1.23). Use this skill to maintain existing Nixpacks builds; for a new project start with Railpack or a Dockerfile.

Instructions

Install

brew install nixpacks        # macOS
cargo install nixpacks       # any platform with a Rust toolchain
scoop install nixpacks       # Windows (the Scoop bucket still ships 1.39.0, which lacks Node 24)

nixpacks --version           # nixpacks 1.41.0 from Homebrew, cargo or the .deb

On Debian or Ubuntu install the .deb from the release page and check it against the SHA-256 that GitHub shows next to the asset:

curl -fsSLO https://github.com/railwayapp/nixpacks/releases/download/v1.41.0/nixpacks-v1.41.0-amd64.deb
echo "995aa2e3cc2986d069e2f7dc19e111d005c48b98bc90eaccec97f001267d8437  nixpacks-v1.41.0-amd64.deb" | sha256sum --check
sudo dpkg -i nixpacks-v1.41.0-amd64.deb

Inspect before building

nixpacks detect ./invoice-api                 # prints the matched providers, e.g. "node"
nixpacks plan ./invoice-api --format toml     # full build plan; JSON is the default format
nixpacks build ./invoice-api --out ./nixpacks-out
# writes ./nixpacks-out/.nixpacks/Dockerfile and does not call Docker

plan and build --out do not need Docker, so they are the fastest way to see what a platform will run.

Build and run

nixpacks build ./invoice-api --name invoice-api
docker run --rm -p 3000:3000 -e PORT=3000 invoice-api

Useful build flags (plan accepts the first four rows too):

nixpacks.toml

Put nixpacks.toml (or nixpacks.json) in the app root. It is merged over the provider's plan; precedence is provider, then file, then environment variables, then CLI flags.

# nixpacks.toml
[phases.setup]
nixPkgs = ["...", "ffmpeg"]          # "..." keeps the provider's packages
aptPkgs = ["...", "libvips-dev"]

[phases.build]
cmds = ["npx prisma generate", "..."]   # run before the provider's build command

[start]
cmd = "node dist/server.js"

[variables]
NEXT_TELEMETRY_DISABLED = "1"

An array without "..." replaces the provider's value. nixPkgs = ["ffmpeg"] on a Node app removes nodejs from the image and the build then fails at npm ci.

Keys available in any [phases.<name>] table: cmds, nixPkgs, nixLibs, aptPkgs, nixOverlays, nixpkgsArchive, dependsOn, cacheDirectories, onlyIncludeFiles, paths. Top-level keys: providers, buildImage, [variables], [staticAssets]. [start] takes cmd, runImage, onlyIncludeFiles. Unknown keys are ignored without a warning, so a typo silently does nothing.

Extra phases are allowed and ordered with dependsOn: define [phases.lint] with cmds = ["npm run lint"] and dependsOn = ["install"], then add dependsOn = ["...", "lint"] under [phases.build].

Pin language versions

There is no version key in nixpacks.toml. Versions come from project files or from provider variables:

Provider variables must reach Nixpacks as build variables: pass --env NIXPACKS_NODE_VERSION=22 on the CLI, put them in [variables], or set them as service variables on the hosting platform. Exporting them in the shell is not enough.

nixpacks plan ./invoice-api --format toml --env NIXPACKS_NODE_VERSION=22 | grep nodejs
#     'nodejs_22',

More than one language

Only one provider is auto-detected: a repository with both package.json and requirements.txt is built as Node and the Python dependencies are never installed. Add the second provider explicitly:

# nixpacks.toml — Node app that also runs a Python report script at build time
providers = ["...", "python"]

[phases.build]
cmds = ["...", "python scripts/build_reports.py"]

[start]
cmd = "node server.js"

The second provider's phases appear in the plan as python:setup and python:install. Only one process starts: a Procfile (web: first, then worker:) or [start].cmd decides which. A release: line in the Procfile becomes an extra phase that runs after the build.

Detection

Elixir (mix.exs), Deno (deno.json), C# (*.csproj), Clojure, COBOL, Crystal, Dart, F#, Gleam, Haskell, Scala, Scheme, Swift and Zig also have providers.

Environment variables

This is how builds are configured on Railway, Coolify and Dokploy, where the CLI flags are not exposed: set these as service variables or commit a nixpacks.toml.

GitHub Actions

# .github/workflows/image.yml
name: Build image
on:
  push:
    branches: [main]

jobs:
  build:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      packages: write
    steps:
      - uses: actions/checkout@v4

      - name: Install Nixpacks 1.41.0
        run: |
          curl -fsSLO https://github.com/railwayapp/nixpacks/releases/download/v1.41.0/nixpacks-v1.41.0-amd64.deb
          echo "995aa2e3cc2986d069e2f7dc19e111d005c48b98bc90eaccec97f001267d8437  nixpacks-v1.41.0-amd64.deb" | sha256sum --check
          sudo dpkg -i nixpacks-v1.41.0-amd64.deb

      - name: Log in to GHCR
        run: echo "${{ secrets.GITHUB_TOKEN }}" | docker login ghcr.io -u ${{ github.actor }} --password-stdin

      - name: Build and push
        run: |
          nixpacks build . --name ghcr.io/${{ github.repository }}:${{ github.sha }}
          docker push ghcr.io/${{ github.repository }}:${{ github.sha }}

github.repository must be lowercase for GHCR. For multi-architecture images run one build per --platform and join them with docker manifest.

Moving to Railpack

Railpack is a separate tool with its own CLI and config, not a drop-in upgrade: it builds through BuildKit directly (BUILDKIT_HOST must point at a BuildKit instance), is configured with railpack.json and RAILPACK_* variables, and installs language runtimes with Mise instead of Nix. nixpacks.toml is not read by Railpack. Its documentation is at https://railpack.com.

Examples

Example 1: Add ffmpeg to a Node service that deploys with Nixpacks

User request: "My Express API on Coolify uses Nixpacks. It needs ffmpeg and Node 22, and the build should run prisma generate first."

Add "engines": { "node": "22" } to package.json, then create the config:

# nixpacks.toml
[phases.setup]
nixPkgs = ["...", "ffmpeg"]

[phases.build]
cmds = ["npx prisma generate", "..."]

[start]
cmd = "node dist/server.js"

Check the result locally before pushing:

nixpacks plan . --format toml

The relevant part of the output:

[phases.build]
dependsOn = ['install']
cmds = [
    'npx prisma generate',
    'npm run build',
]

[phases.setup]
nixPkgs = [
    'nodejs_22',
    'npm-9_x',
    'openssl',
    'ffmpeg',
]

nodejs_22 and ffmpeg are both listed, so the config is correct (openssl is added by the Node provider whenever package.json or the lockfile mentions prisma). Commit nixpacks.toml and package.json; Coolify picks the file up on the next deploy.

Example 2: A Django build that picks the wrong Python version

User request: "Nixpacks builds my Django app with Python 3.11 but I need 3.12. I put pythonVersion in nixpacks.toml and nothing changed."

pythonVersion is not a Nixpacks key, and unknown keys are ignored. Remove it and pin the version with a file the Python provider reads:

echo "3.12" > .python-version
nixpacks plan . --format toml | grep -A4 'phases.setup'

[phases.setup]
nixPkgs = [
    'python312',
    'postgresql_16.dev',
    'gcc',

The plan now shows python312 (postgresql_16.dev is added automatically because psycopg2 is in requirements.txt). The detected start command is python manage.py migrate && gunicorn reports.wsgi; override it only to add options such as a worker count:

# nixpacks.toml
[start]
cmd = "python manage.py migrate && gunicorn reports.wsgi:application --bind 0.0.0.0:$PORT --workers 4"

Guidelines

• Say plainly that Nixpacks is in maintenance mode when a user is choosing a build tool. Recommend it only for keeping an existing build working; new projects should use Railpack or a Dockerfile.
• Run nixpacks plan . --format toml after every config change. It is instant, needs no Docker, and shows exactly which packages and commands will run.
• Always include "..." when adding to nixPkgs, aptPkgs, nixLibs, cmds or providers. Leaving it out is the most common cause of "command not found" in a Nixpacks build.
• Pin the Node version. The default is still Node 18, which is past end of life.
• Do not pass secrets with --env or [variables]: every variable becomes an ENV line in the generated Dockerfile and stays in the final image. Give secrets to the container at run time.
• Images are large — a ten-line Node server builds to roughly 950 MB — because the build image and the Nix store ship in the result. Set [start].runImage with onlyIncludeFiles to copy only the built artifact into a smaller runtime image; this works best for static binaries (Go, Rust).
• Cached directories (~/.npm, ~/.cache/pip, node_modules/.cache) are restored for the install and build phases and never appear in the final image. The cache key is a hash of the app's absolute path; use --cache-key in CI where the path changes.
• Prefer nixPkgs over aptPkgs when the package exists at https://search.nixos.org/packages. Use nixLibs for shared libraries that must be on LD_LIBRARY_PATH.
• Install from a package manager or a checksum-verified release asset rather than the install script on nixpacks.com.