How to fix "listen http2 directive is deprecated" after Nginx upgrade

When you upgrade Nginx to version 1.25 or newer, you might run into deprecation warnings:

[warn] 866041#866041: the "listen ... http2" directive is deprecated, use the "http2" directive instead in /etc/nginx/sites-enabled/www.example.com.conf:23

You can also run into these deprecation warnings after a Linux distribution upgrade. Specifically the upgrade from Debian 12 (Bookworm) to Debian 13 (Trixie) upgrades the Nginx package from 1.22 to 1.26.

This can be verified in the APT history logs (/var/log/apt/history.log):

Commandline: apt-get dist-upgrade
Requested-By: ck (1000)
[...] nginx:amd64 (1.22.1-9+deb12u3, 1.26.3-3+deb13u1) [...]

Ubuntu LTS users will run into similar deprecation warnings once they upgrade to the upcoming Ubuntu 26.04 LTS release. The current LTS release (Ubuntu 24.04 Noble) comes with Nginx 1.24. Ubuntu 26.04 LTS (code name Resolute) will ship with Nginx 1.28.

What changed?

In Nginx 1.25, the syntax for enabling http2 has changed.

In previous releases (from Nginx 1.9.5 up to 1.25) the HTTP/2 protocol could be enabled with the following configuration syntax:

server {
  listen 443 ssl http2;
  listen [::]:443 ssl http2;
  server_name www.example.com;
  [... more options ...]
}

This syntax is now deprecated, as http2 must now be enabled using a new config option "http2 on". This config option was added in the ngx_http_v2_module in Nginx 1.25:

Syntax:	http2 on | off;
Default:	http2 off;
Context:	http, server

This directive appeared in version 1.25.1. Enables the HTTP/2 protocol.

At the same time the documentation of the listen option, part of the ngx_http_core_module, now shows this option is deprecated in favor of the http2 directive:

The http2 parameter (1.9.5) configures the port to accept HTTP/2 connections. Normally, for this to work the ssl parameter should be specified as well, but nginx can also be configured to accept HTTP/2 connections without SSL.

The parameter is deprecated, the http2 directive should be used instead.

New configuration syntax

With this information at hand, the new configuration, in a server {} context, should look like this for Nginx 1.25 and newer:

server {
  listen 443 ssl;
  listen [::]:443 ssl;
  http2 on;
  server_name www.example.com;
  [... more options ...]
}

The Nginx config validator (nginx -t) now doesn't show deprecation warnings anymore:

root@debian13:~# nginx -t
nginx: the configuration file /etc/nginx/nginx.conf syntax is ok
nginx: configuration file /etc/nginx/nginx.conf test is successful

Quickly fix all Nginx configurations using sed

With the following sed commands you can quickly fix all the Nginx configurations in /etc/nginx/sites-available/ on a Debian or Ubuntu machine.

Note: Do not run sed commands in /etc/nginx/sites-enabled/ on symbolic links, as the command will remove the symlink!

root@debian13:~# cp -Rp /etc/nginx/sites-available ~/nginx-sites-available-bkp
root@debian13:~# cd /etc/nginx/sites-available
root@debian13:/etc/nginx/sites-available# sed -i "/listen/s/ http2//g" *.conf
root@debian13:/etc/nginx/sites-available# sed -i "/listen 443/ a\  http2 on;" *.conf
root@debian13:/etc/nginx/sites-available# nginx -t
nginx: the configuration file /etc/nginx/nginx.conf syntax is ok
nginx: configuration file /etc/nginx/nginx.conf test is successful

You might have to adjust the commands a bit according to your original configuration style, e.g. different number of spaces in front of "http2 on;".