> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sevalla.com/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> These are the docs for Sevalla, a platform for deploying applications, databases, static sites, object storage and load balancers. The dashboard is at https://app.sevalla.com.
> Bold text in steps is an exact dashboard label.
> To act on a Sevalla account, prefer the Sevalla MCP server (https://mcp.sevalla.com/mcp, see https://docs.sevalla.com/ai-agents/overview.md), then the Sevalla CLI (https://docs.sevalla.com/developer-tools/cli.md), then the REST API (https://api-docs.sevalla.com, OpenAPI spec at https://api.sevalla.com/v3/openapi.json).
> Every page index is at https://docs.sevalla.com/llms.txt.

# Nixpacks

> Build an application with Nixpacks, Sevalla's default build strategy: supported languages, Nixpacks versions, language versions, nixpacks.toml, NIXPACKS_ variables and the start command.

Nixpacks is an open-source builder from Railway that detects your application's language and framework from the repository and builds a container image with no configuration. It's Sevalla's default build strategy: every new application from Git builds with Nixpacks 1.41. The Nixpacks project is in maintenance mode; [Railpack](/applications/builds/railpack) is its successor.

## How Nixpacks builds your application

Nixpacks reads the files in the [build path](/applications/builds/overview#build-settings) to pick a provider (for example `package.json` for Node.js or `requirements.txt` for Python), then builds in four phases, which the build log prints as a table:

| Phase | What it does | Example for Node.js |
| - | - | - |
| `setup` | Installs the language and system packages | `nodejs_22`, `npm-10_x` |
| `install` | Installs dependencies | `npm ci` |
| `build` | Runs the build script | `npm run build` |
| `start` | The command the container starts with | `npm start` |

If the web process has a start command on the [Processes](/applications/processes) tab, Sevalla passes it to Nixpacks and runs it instead of the detected `start` command.

## Supported languages

Nixpacks detects Clojure, Cobol, Crystal, C#/.NET, Dart, Deno, Elixir, F#, Gleam, Go, Haskell, Java, Lunatic, Node.js (with npm, Yarn, pnpm or Bun), PHP, Python, Ruby, Rust, Scala, Scheme, Swift, Zig, and static files. The [Nixpacks providers documentation](https://nixpacks.com/docs/providers) describes how each is detected and built. For anything else, use a [Dockerfile](/applications/builds/dockerfile).

## Use Nixpacks

<Steps>
  <Step title="Open the build strategy">
    In the sidebar, click **Applications**, then click the application. On the **Settings** tab, in the **Build strategy** section, click **Update build strategy**.
  </Step>

  <Step title="Choose Nixpacks">
    Click **Nixpacks**. Set the **Build path** if the application isn't at the repository root, and choose the **Nixpacks version**.
  </Step>

  <Step title="Save and deploy">
    Click **Update build strategy**, then deploy the application.
  </Step>
</Steps>

The deployment's build log starts with a `Nixpacks v1.41.0` table (or the version you chose) listing the four phases.

## Nixpacks version

| Version | Notes |
| - | - |
| **1.41** | The default for new applications |
| **1.39** | |
| **1.29** | Applications without a saved version build with 1.29 |

Newer versions add language versions and change defaults, so a version change can change how your application builds. Read the [Nixpacks release notes](https://github.com/railwayapp/nixpacks/releases) before you switch, and pin your language version in the repository so the build doesn't depend on Nixpacks' default.

## Set the language version

Without a version in your repository, Nixpacks uses its own default for the language, which depends on the Nixpacks version. Set the version in your files, or with an [environment variable](/applications/environment-variables) marked **Available during buildtime**.

| Language | Set the version with |
| - | - |
| Node.js | `engines.node` in `package.json` (for example `"22"`), an `.nvmrc` file, or `NIXPACKS_NODE_VERSION`. Only a major version: `22` or `22.x`. |
| Python | `NIXPACKS_PYTHON_VERSION`, a `.python-version` file (`3.12`), a `runtime.txt` file (`python-3.12`), `python_version` in the `Pipfile`, or `.tool-versions`. Nixpacks 1.41 supports Python 3.7 to 3.13. |
| PHP | `require.php` in `composer.json`, for example `"php": "8.3"`. PHP 8.1 or later. |
| Go | The `go` directive in `go.mod`, for example `go 1.23` |
| Ruby | A `.ruby-version` file, or the `ruby` line in the `Gemfile` |
| Java | `NIXPACKS_JDK_VERSION`, and `NIXPACKS_GRADLE_VERSION` for Gradle |

```json package.json theme={null}
{
  "engines": {
    "node": "22"
  }
}
```

Nixpacks 1.41 installs Python 3.12 when the repository doesn't set a version. It doesn't fail on a version it doesn't support, such as 3.14: it builds with Python 3.12 instead, so check the `setup` phase in the build log. For Python 3.14, use [Railpack](/applications/builds/railpack) or a [Dockerfile](/applications/builds/dockerfile).

PHP extensions come from `composer.json` too: add them to `require`, for example `"ext-redis": "*"` or `"ext-imagick": "*"`. Python dependencies and their versions come from your dependency file (`requirements.txt`, `poetry.lock`, `uv.lock`, `Pipfile` and others); set `NIXPACKS_PYTHON_PACKAGE_MANAGER` to force one.

## Configure the build

Most applications build with no configuration. To change a phase, add a `nixpacks.toml` file to the build path:

```toml nixpacks.toml theme={null}
[phases.setup]
nixPkgs = ["...", "ffmpeg"]
aptPkgs = ["...", "libvips"]

[phases.build]
cmds = ["npm run build:server"]

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

`"..."` keeps the packages Nixpacks detects and adds yours. The [Nixpacks configuration file reference](https://nixpacks.com/docs/configuration/file) lists every key.

The same settings work as environment variables marked **Available during buildtime**:

| Variable | What it does |
| - | - |
| `NIXPACKS_INSTALL_CMD` | Replaces the install command |
| `NIXPACKS_BUILD_CMD` | Replaces the build command |
| `NIXPACKS_START_CMD` | Replaces the start command |
| `NIXPACKS_PKGS` | Adds Nix packages |
| `NIXPACKS_APT_PKGS` | Adds apt packages, separated by commas |
| `NIXPACKS_LIBS` | Adds Nix libraries |
| `NIXPACKS_INSTALL_CACHE_DIRS` | Adds directories to cache in the install phase |
| `NIXPACKS_BUILD_CACHE_DIRS` | Adds directories to cache in the build phase |
| `NIXPACKS_NO_CACHE` | Turns off Nixpacks' own caching for the build |
| `NIXPACKS_CONFIG_FILE` | Reads the configuration from another file, relative to the build path |

A start command set on the web process wins over `nixpacks.toml` and `NIXPACKS_START_CMD`. Define other processes, such as workers, on the [Processes](/applications/processes) tab.

## Procfile

Nixpacks reads a `Procfile` in the build path. Its `web` entry (or `worker`, or else the first entry) becomes the image's start command; a start command on the web process still wins. Sevalla doesn't create processes from the other entries: create them on the [Processes](/applications/processes) tab.

A `release` entry runs once, as the last step of the build, not before each deployment. It doesn't run on restarts, rollbacks or promotions, and it gets only the variables available during the build. For release tasks such as database migrations, remove the `release` entry and create a [job](/applications/processes#jobs) with the start policy **Before deployment**.

## Frequently asked questions

<AccordionGroup>
  <Accordion title="Can I run Composer?">
    Yes. When the repository has a `composer.json`, Nixpacks installs PHP and runs Composer to install its dependencies. Declare PHP extensions in the same file's `require` section.
  </Accordion>

  <Accordion title="How do I pin a Python package version?">
    In your dependency file, for example `Django==5.1` in `requirements.txt`. Set the Python version itself with a `.python-version` file.
  </Accordion>

  <Accordion title="My language isn't detected">
    Check the **Build path**: Nixpacks looks for the language's files in that folder, not in the repository root. If the language isn't supported, switch to [Railpack](/applications/builds/railpack) or a [Dockerfile](/applications/builds/dockerfile).
  </Accordion>
</AccordionGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.