AutoPort

Never fight over port 4000 again.

A tiny, dependency-free Elixir library that finds an available local TCP port.

It exists to make running several Phoenix applications at the same time painless: the first one takes 4000, the next 4001, the next 4002, without anybody editing config.

Installation

Add autoport as a development-only dependency:

def deps do
  [
    {:autoport, "~> 1.0", only: :dev}
  ]
end

Phoenix usage

In config/dev.exs:

config :my_app, MyAppWeb.Endpoint,
  http: [
    ip: {127, 0, 0, 1},
    port: AutoPort.find(4000)
  ]

If 4000 is taken, AutoPort prints Port 4000 is in use, using 4001 and your app boots on the next free port.

Choosing a port explicitly

PORT overrides whatever the config asks for, so you can pin a shell to a known port:

$ PORT=4050 iex -S mix phx.server

The search still walks upwards from there, so two shells that both export PORT=4050 land on 4050 and 4051 rather than one failing to boot. Pass env: false to honour the configured target verbatim, or env: "MY_APP_PORT" to read a different variable.

API

# First free port at or after 4000, raising only if 4000..65535 is fully taken.
AutoPort.find(4000)
#=> 4000

# Bounded search; raises AutoPort.Error if every port in the range is taken.
AutoPort.find(4000..4010)
#=> 4001

# Non-raising variant.
AutoPort.fetch(4000..4010)
#=> {:ok, 4001}
#=> {:error, "no available port found in 4000..4010"}

# Single-port check.
AutoPort.available?(4000)
#=> false

Options

AutoPort.find(4000, ip: {0, 0, 0, 0}, verbose: false)

Scope

AutoPort is framework-agnostic — no Phoenix, Plug, Bandit, or Cowboy dependency. It is meant for local development; production deployments should keep using deterministic, explicitly configured ports.

There is an inherent race between checking a port and binding it. In practice this is a non-issue for local development, but it is another reason not to use this in production.

License

MIT.