Dashboard

Build and deploy

Runtime versions

Choose the language version your app builds and runs with.

An automatic build picks a language version from your project's files. To choose a different one, set Runtime version (optional) in the project's settings, or pin it in a version file in your repository. A Dockerfile build takes its version from your Dockerfile.

How the version is chosen

Without a setting, the build uses what your project asks for:

  • Node.js: an .nvmrc or .node-version file, a node entry in .tool-versions, or the engines.node range in package.json. If engines.node is only a lower bound below 22, such as >=18, HCode builds with Node 22, and the build log says "Node version: package.json asks for Node" followed by the range and the version it installed.
  • Python: .python-version.
  • Java: Java 21, or the version a Gradle toolchain asks for (JavaLanguageVersion.of(17) or jvmToolchain(17)). HCode sets JAVA_HOME to the Java it installs, so don't set it yourself.
  • Bun: the newest Bun release, so a lockfile written by a recent Bun can be read.

A version named without its patch number, such as 3.14, only matches releases that are more than 14 days old. To build with a newer release, name it in full, for example 3.14.0.

Languages

Language Example version Automatic build Dockerfile build argument
Node.js 22 Settings, .nvmrc, .node-version, .tool-versions or engines.node NODE_VERSION
Bun 1.2 Settings BUN_VERSION
Deno 2 Settings DENO_VERSION
Python 3.13.1 Settings or .python-version PYTHON_VERSION
Go 1.24 Settings GO_VERSION
Java 21 Settings or a Gradle toolchain JAVA_VERSION
Ruby 3.4 Settings RUBY_VERSION
Rust 1.85 Settings RUST_VERSION
Elixir 1.18 Settings ELIXIR_VERSION
Erlang 27 Settings ERLANG_VERSION
.NET 9.0 Settings DOTNET_VERSION

"Settings" is the Runtime version (optional) control described below. The Dockerfile argument only does anything if your Dockerfile declares it; see Dockerfile builds.

Set a version in settings

  1. Open the project's Settings and go to Build configuration.
  2. Under Runtime version (optional), pick the language: Node.js, Bun, Deno, Python, Go, Java, Ruby, Rust, Elixir, Erlang or .NET.
  3. Type the version, for example 22, 3.13.1 or 21. Leave it empty to use what your project asks for.
  4. Click Save changes, then deploy again.

For an automatic build, the version is saved as an environment variable; the line under the field shows its name. It appears in the project's environment variables, and deleting it there removes the setting. A version file in the repository, such as .nvmrc or .python-version, can take precedence over it.

For Node.js, an environment variable called NODE_VERSION also works if you haven't set the version any other way.

Dockerfile builds

A Dockerfile picks its version in FROM, so HCode can't change it from outside. The same setting is passed to the build as a build argument instead: NODE_VERSION for Node.js, PYTHON_VERSION for Python, JAVA_VERSION for Java and so on. The line under the field names the argument for the language you picked.

It only takes effect if your Dockerfile declares the argument before a FROM that uses it:

dockerfile
ARG NODE_VERSION=22
FROM node:${NODE_VERSION}-alpine

The setting is stored with your other build arguments. Here a version may only use letters, digits and ., +, _ or -, up to 32 characters, and anything else is refused when you save. Deploy again to apply it.

When the version can't be installed

If the build can't install the version you asked for, it fails with a message such as "The build could not install Python 3.15." The details say which file or setting to change. Build failures lists this and the other version errors.