How to Install Nginx Mainline on Debian Linux

Nginx Mainline provides the latest features, bug fixes, and performance improvements for the Nginx web server before they reach the stable branch. On Debian, installing from the official nginx.org repository gives you immediate access to upstream development, ideal if you need to host high-traffic websites, configure reverse proxies, or experiment with new Nginx capabilities. By the end of this guide, you will have Nginx Mainline installed on Debian with APT pinning configured to ensure future updates come from the correct source.

Contents hide

1 Choose Your Nginx Version

2 Prepare Your Debian System

3 Import the Nginx.org Repository

4 Install Nginx Mainline

Choose Your Nginx Version

The nginx.org repository offers two branches, both significantly newer than Debian’s default packages:

Branch	Version	Update Frequency	Best For
nginx.org Mainline	Latest development	Monthly	Latest features, frequent updates
nginx.org Stable	Latest stable	Every few months	Production servers, critical fixes only
Debian Repos	Distribution default	When Debian backports	Distro-tested packages

Mainline

Receives new features, optimizations, and bug fixes first
New versions release roughly once per month
Each release goes through the same rigorous testing as stable
Proven reliable for high-traffic reverse proxies and content delivery in production environments

Choose mainline when you need HTTP/3 enhancements, modern TLS cipher support, or faster security patch deployment. The “development” label refers to feature velocity, not stability risk.

Stable

Receives only critical bug fixes and security patches backported from mainline
Updates typically every few months
Longer intervals between releases for predictable change management

Choose stable if your deployment requires change control procedures that make frequent updates impractical, or if you depend on third-party modules that lag behind mainline compatibility.

Debian Default Packages

Lag significantly behind both nginx.org branches (often by a year or more)
Debian prioritizes distribution stability over feature velocity
Security patches may arrive later than upstream releases

For a web server handling modern protocols and security requirements, the nginx.org repository provides a better balance of stability and currency.

This guide uses the mainline branch. To install stable instead, substitute /packages/mainline/debian with /packages/debian in the repository URI.

Prepare Your Debian System

Update System Packages

First, update your package lists and upgrade existing packages to ensure your system has the latest security patches:

sudo apt update && sudo apt upgrade

Install Required Packages

Next, install the packages needed to add and verify the nginx.org repository:

sudo apt install -y curl gnupg ca-certificates lsb-release

Import the Nginx.org Repository

Download the Nginx GPG Key

To begin, download and store the official Nginx signing key to verify package authenticity:

curl -fsSL https://nginx.org/keys/nginx_signing.key | sudo gpg --dearmor -o /usr/share/keyrings/nginx-archive-keyring.gpg

Then, verify the key was imported correctly:

gpg --dry-run --quiet --import --import-options import-show /usr/share/keyrings/nginx-archive-keyring.gpg

As a result, you should see output showing multiple signing keys:

pub   rsa4096 2024-05-29 [SC]
      8540A6F18833A80E9C1653A42FD21310B49F6B46
uid                      nginx signing key <signing-key-2@nginx.com>

pub   rsa2048 2011-08-19 [SC] [expires: 2027-05-24]
      573BFD6B3D8FBC641079A6ABABF5BD827BD9BF62
uid                      nginx signing key <signing-key@nginx.com>

pub   rsa4096 2024-05-29 [SC]
      9E9BE90EACBCDE69FE9B204CBCDCD8A38D88A2B3
uid                      nginx signing key <signing-key-3@nginx.com>

Add the Nginx Repository

Now, add the nginx.org mainline repository to your system using the modern DEB822 format. This command automatically detects your Debian version:

cat <<EOF | sudo tee /etc/apt/sources.list.d/nginx.sources
Types: deb
URIs: https://nginx.org/packages/mainline/debian
Suites: $(lsb_release -cs)
Components: nginx
Architectures: $(dpkg --print-architecture)
Signed-By: /usr/share/keyrings/nginx-archive-keyring.gpg
EOF

If you prefer the stable branch instead of mainline, change the URIs line to https://nginx.org/packages/debian instead of /packages/mainline/debian.

Debian 13 (trixie) defaults to DEB822 .sources format shown above. Debian 12 (bookworm) and Debian 11 (bullseye) fully support .sources, but if you prefer the legacy format, use: echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/nginx-archive-keyring.gpg] https://nginx.org/packages/mainline/debian $(lsb_release -cs) nginx" | sudo tee /etc/apt/sources.list.d/nginx.list

Configure APT Pinning

Additionally, configure APT to prefer packages from nginx.org over Debian’s default repositories. First, update package lists to fetch the repository metadata, then verify the actual Origin string:

sudo apt update
cat /var/lib/apt/lists/*nginx*_InRelease | grep '^Origin:'

Expected output confirming the Origin field:

Origin: nginx

Now create the pin configuration using the verified Origin:

echo -e "Package: *\nPin: release o=nginx\nPin-Priority: 900" | sudo tee /etc/apt/preferences.d/99nginx

The expected output confirms the configuration:

Package: *
Pin: release o=nginx
Pin-Priority: 900

The pin uses release o=nginx which matches the Origin field in the repository’s InRelease metadata. Always verify the actual Origin before creating pins, because domain names often don’t match the Origin field.

Verify Repository Configuration

Verify APT recognizes the nginx.org repository and applies the correct priority:

apt-cache policy nginx

In particular, you should see the nginx.org repository listed with higher priority:

nginx:
  Installed: (none)
  Candidate: 1.x.x-1~bookworm
  Version table:
     1.x.x-1~bookworm 900
        900 https://nginx.org/packages/mainline/debian bookworm/nginx amd64 Packages
     1.x.x-x+debXXuX 500
        500 http://deb.debian.org/debian bookworm/main amd64 Packages

The version numbers and codename will vary based on your Debian version. The key indicator is that the nginx.org repository appears with a priority of 900, higher than the default 500. If you only see 500 for both sources, the pin configuration is incorrect.

Install Nginx Mainline

With the repository configured, you can now install Nginx:

sudo apt install nginx

Afterward, verify the installation by checking the installed version:

nginx -v

Accordingly, the expected output shows:

nginx version: nginx/1.x.x

As a result, the version should be higher than what Debian’s default repositories provide, confirming you installed from nginx.org.

Enable and Start Nginx

Next, enable Nginx to start automatically at boot and start the service:

sudo systemctl enable nginx --now

Then, verify Nginx is running:

systemctl status nginx

Consequently, you should see output showing active status:

● nginx.service - nginx - high performance web server
     Loaded: loaded (/lib/systemd/system/nginx.service; enabled; preset: enabled)
     Active: active (running) since Mon 2025-12-02 10:00:00 UTC; 5s ago
       Docs: https://nginx.org/en/docs/
    Process: 1234 ExecStart=/usr/sbin/nginx -c /etc/nginx/nginx.conf (code=exited, status=0/SUCCESS)
   Main PID: 1235 (nginx)
      Tasks: 2 (limit: 4915)
     Memory: 2.1M
        CPU: 15ms
     CGroup: /system.slice/nginx.service

Verify Configuration Syntax

Before making any configuration changes, always test the Nginx configuration syntax first:

sudo nginx -t

Upon success, you will see the following output:

nginx: the configuration file /etc/nginx/nginx.conf syntax is ok
nginx: configuration file /etc/nginx/nginx.conf test is successful

However, if there’s a syntax error, you’ll see output like:

nginx: [emerg] unexpected ";" in /etc/nginx/conf.d/default.conf:12
nginx: configuration file /etc/nginx/nginx.conf test failed

In that case, fix the error in the indicated file and line number, then run nginx -t again before reloading.

Test the Default Page

Finally, verify Nginx is serving content by requesting the default page:

curl -I http://localhost

In response, you should see HTTP 200:

HTTP/1.1 200 OK
Server: nginx/1.x.x
Content-Type: text/html
...

Alternatively, if you have a desktop environment, open http://localhost in a browser to see the Nginx welcome page.

Manage Nginx

At this point, here are common commands for managing your Nginx installation:

First, to reload configuration without downtime:

sudo systemctl reload nginx

The reload command gracefully applies configuration changes while keeping existing connections active. Nginx spawns new worker processes with the updated configuration and allows old workers to finish handling current requests before terminating. For production servers, always prefer reload over restart when applying configuration changes.

Alternatively, for a full restart of Nginx:

sudo systemctl restart nginx

A full restart stops all worker processes immediately and starts fresh. This briefly drops active connections, so use it only when reload fails or after major changes like upgrading the Nginx binary.

And to stop Nginx entirely:

sudo systemctl stop nginx

Update Nginx

Generally, Nginx will update automatically with your regular system updates:

sudo apt update && sudo apt upgrade

However, to update only Nginx without upgrading other packages:

sudo apt update && sudo apt install --only-upgrade nginx

Important File Locations

Below are the key directories and files for Nginx configuration:

/etc/nginx/nginx.conf: Main configuration file
/etc/nginx/conf.d/: Server block configurations (virtual hosts)
/var/log/nginx/access.log: Access log
/var/log/nginx/error.log: Error log
/usr/share/nginx/html/: Default document root

Troubleshoot Nginx

Port 80 Already in Use

If Nginx fails to start with this error:

nginx: [emerg] bind() to 0.0.0.0:80 failed (98: Address already in use)
nginx: [emerg] still could not bind()

In this case, another service is using port 80. To identify the process, check which one is using the port:

sudo lsof -i :80

For instance, output showing Apache is using port 80 might look like this:

COMMAND   PID     USER   FD   TYPE DEVICE SIZE/OFF NODE NAME
apache2  1234     root    4u  IPv6  12345      0t0  TCP *:http (LISTEN)

Once identified, stop the conflicting service:

sudo systemctl stop apache2

Afterward, start Nginx and verify it runs correctly:

sudo systemctl start nginx && systemctl status nginx

Check Error Logs

When Nginx fails to start or behaves unexpectedly, first check the error log:

sudo tail -50 /var/log/nginx/error.log

Common errors you might see include:

2025/12/02 10:15:30 [emerg] 1234#1234: open() "/etc/nginx/nginx.conf" failed (2: No such file or directory)
2025/12/02 10:15:45 [emerg] 1234#1234: host not found in upstream "backend" in /etc/nginx/conf.d/default.conf:12

Additionally, check the systemd journal for startup errors:

journalctl -xeu nginx

Example journal output showing a configuration error:

Dec 02 10:15:30 debian nginx[1234]: nginx: [emerg] unexpected ";" in /etc/nginx/conf.d/default.conf:12
Dec 02 10:15:30 debian systemd[1]: nginx.service: Control process exited, code=exited, status=1/FAILURE

After identifying and fixing the issue, test the configuration and restart:

sudo nginx -t && sudo systemctl restart nginx && systemctl status nginx

Permission Denied Errors

Similarly, if logs show permission denied errors for files in your document root, verify ownership:

ls -la /usr/share/nginx/html/

Correct permissions look like this:

drwxr-xr-x 2 root root 4096 Dec  2 10:00 .
-rw-r--r-- 1 root root  497 Dec  2 10:00 50x.html
-rw-r--r-- 1 root root  615 Dec  2 10:00 index.html

If you see restrictive permissions like -rw------- (owner-only) or ownership by a different user, Nginx cannot read the files. Fix permissions as follows:

sudo chown -R root:root /usr/share/nginx/html/
sudo chmod -R 755 /usr/share/nginx/html/

Verify the fix by testing the configuration and confirming Nginx can serve content:

sudo nginx -t && curl -I http://localhost

Expected output confirming the fix:

nginx: the configuration file /etc/nginx/nginx.conf syntax is ok
nginx: configuration file /etc/nginx/nginx.conf test is successful
HTTP/1.1 200 OK
Server: nginx/1.x.x

Remove Nginx

If you no longer need Nginx, follow these steps to completely remove it and the nginx.org repository from your system:

Uninstall Nginx Packages

sudo systemctl stop nginx
sudo systemctl disable nginx
sudo apt remove --purge nginx nginx-common nginx-full 'nginx-module-*' -y
sudo apt autoremove -y

Remove Repository Configuration

sudo rm -f /etc/apt/sources.list.d/nginx.sources /etc/apt/sources.list.d/nginx.list
sudo rm -f /etc/apt/preferences.d/99nginx
sudo rm -f /usr/share/keyrings/nginx-archive-keyring.gpg
sudo apt update

Verify Removal

apt-cache policy nginx

Consequently, expected output shows only Debian’s default package (or no package at all):

nginx:
  Installed: (none)
  Candidate: 1.x.x-x+debXXuX
  Version table:
     1.x.x-x+debXXuX 500
        500 http://deb.debian.org/debian bookworm/main amd64 Packages

Caution: Configuration files in /etc/nginx/ may remain after uninstallation. If you have custom server blocks, SSL certificates, or other configurations you might need later, back them up before removing the directory.

To completely remove all configuration files:

sudo rm -rf /etc/nginx/

Conclusion

You now have Nginx Mainline installed from the official nginx.org repository on Debian with APT pinning configured to ensure consistent updates. To secure your deployment, consider adding Let’s Encrypt SSL certificates, Gzip compression, or Fail2ban protection.