How to Configure the Server Port in Spring Boot

By the end of this page, you will understand how Spring Boot chooses its server port and how to change it using application.properties, application.yml, command-line arguments, environment variables, and Java configuration. You will also see when each approach is most useful in real projects.

Spring Boot applications that include a web server starter, such as spring-boot-starter-web, run with an embedded server like Tomcat. By default, that server listens on port 8080.

The port is simply the network endpoint where your application accepts HTTP requests. If another service is already using 8080, or if your deployment environment requires a different port, you need to override that default.

In Spring Boot, the main setting for this is:

server.port=9090

This matters because real applications often run in different environments:

• Local development may use one port
• Testing may use another port
• Production may be assigned a port by the platform
• Containers and cloud platforms may inject the port through environment variables

Spring Boot makes this easy by supporting multiple configuration sources with a clear precedence order. That means the same app can run with different ports without changing code.

Think of your Spring Boot application like a shop in a building.

• The application is the shop
• The port is the shop's door number
• Clients must know the correct door number to enter

If your app is listening on port 8080, that is like saying the shop is at door 8080. Changing server.port is just changing the door number where the shop accepts visitors.

Spring Boot lets you set that door number in several places, such as config files, environment variables, or startup commands.

The most common way to configure the port is in a configuration file.

Using application.properties

server.port=9090

This tells Spring Boot to start the embedded server on port 9090.

Using application.yml

server:
  port: 9090

This does exactly the same thing as the properties example.

Using a command-line argument

java -jar myapp.jar --server.port=9090

This is useful when you want to change the port without editing files.

Using an environment variable

export SERVER_PORT=9090
java -jar myapp.jar

Spring Boot maps SERVER_PORT to server.port automatically.

Using Java code

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;

import java.util.Collections;

@SpringBootApplication
public class DemoApplication {
    public static void main(String[] args) {
        SpringApplication app = new SpringApplication(DemoApplication.class);
        app.setDefaultProperties(Collections.singletonMap("server.port", "9090"));
        app.run(args);
    }
}

This approach works, but file-based or environment-based configuration is usually preferred because it is easier to change per environment.

Consider this application.properties file:

server.port=9090

And this application:

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;

@SpringBootApplication
public class DemoApplication {
    public static void main(String[] args) {
        SpringApplication.run(DemoApplication.class, args);
    }
}

@RestController
class HelloController {
    @GetMapping("/hello")
    public String hello() {
        return "Hello";
    }
}

Here is what happens step by step:

1. Spring Boot starts the application from main().
2. During startup, it loads configuration from known sources, including application.properties.
3. It finds server.port=9090.
4. The embedded web server is created and configured to listen on port 9090.
5. The HelloController registers the /hello endpoint.
6. You access the app at:

http://localhost:9090/hello

If server.port were not set, the same app would usually start on:

http://localhost:8080/hello

Changing the Spring Boot port is common in many situations:

• Avoiding port conflicts

  • If another app is already using 8080, you can run your app on 8081 or 9090.

• Running multiple services locally

  • A frontend app might run on 3000
  • One Spring Boot API on 8081
  • Another on 8082

• Environment-specific deployment

  • Development: 8081
  • Staging: 9080
  • Production: assigned by infrastructure

• Containerized applications

  • The internal port may be fixed, but environment variables can still be used for flexibility.

• Platform deployment

  • Some cloud platforms provide the port dynamically, and your app must read it from configuration.

• Integration testing

  • Tests may use a random or custom port to avoid clashes with other running services.

In real projects, developers usually avoid hardcoding ports directly in Java code. Instead, they prefer external configuration so the same application artifact can run in multiple environments.

Common patterns include:

Environment-based configuration

A team may store the default in application.properties:

server.port=8081

Then override it in production with an environment variable:

SERVER_PORT=80

Profile-specific configuration

Spring Boot supports profile files such as:

• application-dev.properties
• application-test.properties
• application-prod.properties

Example:

# application-dev.properties
server.port=8081

# application-prod.properties
server.port=80

Command-line overrides in deployment scripts

Deployment tools often run:

java -jar app.jar --server.port=9091

This is useful for temporary overrides or infrastructure-managed startup scripts.

Random ports in tests

For integration tests, developers often use a random port instead of a fixed one:

server.port=0

When 0 is used, the operating system assigns an available port.

Configuration-first design

The general best practice is:

• Keep config outside code when possible
• Use environment variables in cloud or container deployments
• Use profiles for different environments
• Use command-line overrides for temporary changes

Beginners often run into a few common issues when changing the server port.

1. Putting the property in the wrong file

Spring Boot expects configuration in standard locations such as:

• src/main/resources/application.properties
• src/main/resources/application.yml

Broken example:

# wrong file or wrong folder
server.port=9090

If the file is not loaded, the port will stay at 8080.

2. Using the wrong property name

Broken example:

port=9090

Correct:

server.port=9090

3. YAML indentation errors

Broken example:

server:
port: 9090

Correct:

server:
  port: 9090

YAML depends on indentation.

4. Forgetting that another config source overrides the file

You may set:

server.port=9090

But if the app is started with:

java -jar app.jar --server.port=8085

then 8085 wins.

5. Choosing a port already in use

If another application already uses that port, your app may fail to start.

Example symptom:

Port 9090 was already in use

Choose another port or stop the conflicting process.

6. Hardcoding environment-specific values in Java

Avoid this unless you have a very specific reason:

app.setDefaultProperties(Collections.singletonMap("server.port", "9090"));

This is less flexible than external configuration.

Here is a comparison of the main ways to set the Spring Boot server port:

application.properties vs application.yml

Fixed port vs random port

Quick reference

Set the port in application.properties

server.port=9090

Set the port in application.yml

server:
  port: 9090

Set the port from the command line

java -jar myapp.jar --server.port=9090

Set the port from an environment variable

SERVER_PORT=9090

Use a random available port

server.port=0

Key rule

Spring Boot uses the server.port property to configure the embedded web server port.

Common file location

src/main/resources/application.properties

Typical default

8080

Common problems

• Wrong property name: use server.port
• Wrong YAML indentation
• File not in src/main/resources
• Another config source overriding your value
• Selected port already in use

How do I change the default port in Spring Boot?

Set server.port in application.properties or application.yml.

server.port=9090

What is the default port for a Spring Boot application?

The default port is usually 8080 when running a web application with an embedded server.

Can I set the Spring Boot port using an environment variable?

Yes. Use SERVER_PORT. Spring Boot maps it automatically to server.port.

Can I pass the port when starting the JAR?

Yes.

java -jar app.jar --server.port=9090

Which value wins if I set the port in multiple places?

Spring Boot has a property precedence system. In many common cases, command-line arguments override values from configuration files.

How do I run Spring Boot on a random port?

Set:

server.port=0

The operating system will assign an available port.

Why is my app still starting on port 8080?

Common reasons include:

• The config file is in the wrong location
• The property name is incorrect
• Another configuration source overrides your setting
• The app was not restarted after the change

• Spring Boot configuration properties — server.port is one example of externalized configuration.
• application.properties — A common file for defining Spring Boot settings.
• application.yml — An alternative configuration format using YAML.
• Spring profiles — Useful for setting different ports in dev, test, and production.
• Environment variables — Commonly used to configure applications in containers and cloud platforms.
• Command-line arguments — Often used to override config at startup.
• Embedded Tomcat — The default embedded web server in many Spring Boot web apps.
• Port binding — The networking concept behind how applications listen for requests.