Introduction

Changing a Spring Boot port is mostly a Spring configuration task, but Gradle can be used to pass or enforce that configuration when you run the application. The right approach depends on whether you want a default port in source control or a temporary override for local development.

Set the Default Port in Spring Configuration

The most common solution is still the Spring Boot config file. This is the best choice when the application should normally start on the same non-default port.

server.port=9090

If your project uses YAML:

server:
  port: 9090

This works whether you start the app from Gradle, from your IDE, or from a packaged JAR. The port is part of the application configuration, so it stays consistent across run methods.

Override the Port When Running With Gradle

If you only want to change the port for one local run, pass it as a command-line argument through bootRun.

./gradlew bootRun --args='--server.port=9091'

This is convenient for testing two services side by side or avoiding a port conflict without editing committed config files.

You can do the same with an environment variable:

SERVER_PORT=9092 ./gradlew bootRun

Spring Boot maps SERVER_PORT to server.port, so the application picks it up automatically.

Configure bootRun in build.gradle

If your team wants Gradle to always start the app on a specific port during local development, configure the bootRun task directly.

tasks.named('bootRun') {
    systemProperty 'server.port', '9095'
}

Now every ./gradlew bootRun invocation uses port 9095 unless a higher-precedence setting overrides it.

This is useful for local conventions, but remember what it does and does not affect:

• It changes bootRun
• It does not rewrite application.properties
• It does not automatically change how a packaged JAR runs outside Gradle

Understand Property Precedence

When several sources provide the same setting, Spring Boot uses a precedence order. In practical terms, command-line arguments usually win over environment variables, which usually win over application config files.

So if you have:

• 'server.port=9090 in application.properties'
• 'SERVER_PORT=9092 in the shell'
• '--server.port=9093 in bootRun --args'

the application normally starts on 9093.

Knowing that order makes troubleshooting much easier when the server starts on a different port than you expected.

Use Profile-Specific Ports Carefully

You can also put the port in a profile-specific file such as application-dev.properties:

server.port=9080

Then run:

./gradlew bootRun --args='--spring.profiles.active=dev'

This is a good choice when different environments need different ports and you want that behavior to be explicit rather than hidden inside a build script.

Verify the Running Port

After startup, check the application logs for the embedded server message. Spring Boot will usually report the actual port it bound to, which is helpful when multiple configuration sources are competing.

Common Pitfalls

• Gradle is not the only place to change the port, and often it is not the best permanent place either.
• Setting the port in bootRun affects Gradle runs, but packaged deployments may still use a different value.
• Command-line arguments and environment variables can override config files, which surprises people during debugging.
• Hard-coding a port in build.gradle can confuse teammates if the project already uses profile-based configuration.

Summary

• Use application.properties or application.yml for the normal default port.
• Use ./gradlew bootRun --args='--server.port=...' for temporary overrides.
• Use SERVER_PORT=... ./gradlew bootRun when environment-based config fits your workflow.
• Configure the bootRun task only when you deliberately want Gradle-specific startup behavior.