Installation
Install Orval in your project
Install Orval as a dev dependency in your project.
Package Managers
bun add -d orvalnpm install orval -Dyarn add orval -Dpnpm add orval -DDocker
Orval 8+ requires Node.js 22.18 or newer. If your project targets an older Node LTS version, you can run code generation with the official Docker image instead of installing Orval locally.
/app is only a path inside the container. Your project does not need an app folder — mount your project root to any container path and set -w to match.
Basic usage
docker run --rm -v "$(pwd):/app" -w /app ghcr.io/orval-labs/orvalMSYS_NO_PATHCONV=1 docker run --rm -v "$(pwd):/app" -w /app ghcr.io/orval-labs/orvaldocker run --rm -v "%cd%:/app" -w /app ghcr.io/orval-labs/orvaldocker run --rm -v "${PWD}:/app" -w /app ghcr.io/orval-labs/orvalPin a specific release with a version tag (for example 8.21.0):
ghcr.io/orval-labs/orval:8.21.0With a config file
docker run --rm -v "$(pwd):/app" -w /app ghcr.io/orval-labs/orval --config ./orval.config.tsMSYS_NO_PATHCONV=1 docker run --rm -v "$(pwd):/app" -w /app ghcr.io/orval-labs/orval --config ./orval.config.tsdocker run --rm -v "%cd%:/app" -w /app ghcr.io/orval-labs/orval --config ./orval.config.tsdocker run --rm -v "${PWD}:/app" -w /app ghcr.io/orval-labs/orval --config ./orval.config.tsOn Windows Git Bash, prefix commands with MSYS_NO_PATHCONV=1 so Docker receives /app instead of C:/Program Files/Git/app.
Fetching OpenAPI from localhost
Inside a container, localhost refers to the container itself, not your machine. If your orval.config.ts fetches a spec from a local API (for example https://localhost:7142/swagger/v1/swagger.json), replace localhost with host.docker.internal and pass the URL via an environment variable.
| Host OS | Use instead of localhost |
|---|---|
| Windows / macOS (Docker Desktop) | host.docker.internal |
| Linux (Docker Desktop) | host.docker.internal |
| Linux (native Docker) | host.docker.internal with --add-host=host.docker.internal:host-gateway |
Read the URL from an environment variable in your config:
const inputTarget =
process.env.ORVAL_SWAGGER_URL ?? 'https://localhost:7142/swagger/v1/swagger.json';Set NODE_TLS_REJECT_UNAUTHORIZED=0 only when your local API uses a self-signed certificate. For CI or offline builds, point Orval at a committed file such as ./src/swagger.json instead.
Replace ghcr.io/orval-labs/orval with orval:local when testing with a locally built image before the official image is published.
docker run --rm \
-v "$(pwd):/app" \
-w /app \
-e ORVAL_SWAGGER_URL="https://host.docker.internal:7142/swagger/v1/swagger.json" \
-e NODE_TLS_REJECT_UNAUTHORIZED=0 \
ghcr.io/orval-labs/orval \
--config ./orval.config.tsdocker run --rm --add-host=host.docker.internal:host-gateway \
-v "$(pwd):/app" \
-w /app \
-e ORVAL_SWAGGER_URL="https://host.docker.internal:7142/swagger/v1/swagger.json" \
-e NODE_TLS_REJECT_UNAUTHORIZED=0 \
ghcr.io/orval-labs/orval \
--config ./orval.config.tsMSYS_NO_PATHCONV=1 docker run --rm \
-v "$(pwd):/app" \
-w /app \
-e ORVAL_SWAGGER_URL="https://host.docker.internal:7142/swagger/v1/swagger.json" \
-e NODE_TLS_REJECT_UNAUTHORIZED=0 \
ghcr.io/orval-labs/orval \
--config ./orval.config.tscd /d "C:\path\to\your-project"
docker run --rm -v "%cd%:/app" -w /app -e ORVAL_SWAGGER_URL=https://host.docker.internal:7142/swagger/v1/swagger.json -e NODE_TLS_REJECT_UNAUTHORIZED=0 ghcr.io/orval-labs/orval --config ./orval.config.tscd "C:\path\to\your-project"
docker run --rm -v "${PWD}:/app" -w /app -e ORVAL_SWAGGER_URL="https://host.docker.internal:7142/swagger/v1/swagger.json" -e NODE_TLS_REJECT_UNAUTHORIZED=0 ghcr.io/orval-labs/orval --config ./orval.config.tsGlobal Installation
You can also install Orval globally:
bun add -g orvalnpm install orval -gyarn global add orvalpnpm add orval -gVerify Installation
After installation, verify that Orval is installed correctly:
bunx orval --versionnpx orval --versionyarn orval --versionpnpm orval --version