Gunicorn Socket Files: How They Work & Where to Store Them

Gunicorn socket files are Unix domain sockets that let a web server like Nginx talk to Gunicorn without using a TCP port. You create the socket when you start Gunicorn, and the web server connects to it. This guide explains how they work and where to put them so your deployment stays clean and secure.

What You’ll Need

• A Linux server (Ubuntu, Debian, CentOS, etc.) with Gunicorn installed
• A web server (Nginx or Apache) configured as a reverse proxy
• Basic familiarity with the command line and systemd (if you use it)

Step-by-Step

1. Understand what a socket file is. A Unix domain socket is a special file that processes use to communicate locally. Gunicorn listens on this file instead of a TCP port. The web server connects to it, so requests flow from the web server to Gunicorn through the file.
2. Choose a location for the socket file. Common choices are /tmp, /var/run, or a directory inside your project. /tmp is simple but world-writable, which can be a security risk. /var/run (or /run) is more standard and often cleared on reboot. Some deployments use /var/www/myapp/gunicorn.sock to keep it with the app. Pick one that your web server user can access.
3. Create the directory if needed. If you choose /var/run/myapp, create it with sudo mkdir -p /var/run/myapp. Then set ownership so the user running Gunicorn can write to it: sudo chown www-data:www-data /var/run/myapp (replace www-data with the user that runs Gunicorn).
4. Start Gunicorn with the socket. Use the --bind option with a unix: prefix. For example: gunicorn --bind unix:/var/run/myapp/gunicorn.sock myapp:app. If you use a systemd service, set ExecStart to that command.
5. Set proper permissions on the socket file. By default, the socket is created with permissions based on your umask. To allow only the web server user to access it, add --umask 007 to the Gunicorn command. This gives rwx to the owner and group, and nothing to others. Ensure the web server user is in the same group as the Gunicorn user.
6. Configure your web server to use the socket. In Nginx, inside the server block, set proxy_pass http://unix:/var/run/myapp/gunicorn.sock;. For Apache, use ProxyPass / unix:/var/run/myapp/gunicorn.sock|http://localhost/ with the proxy module enabled.
7. Restart both services. After changing Gunicorn or the web server config, restart them: sudo systemctl restart gunicorn and sudo systemctl restart nginx. Then test by visiting your site.

Common Mistakes

• Putting the socket in a directory the web server can’t traverse. For example, if the directory has permissions 700 and the web server user is not the owner, it can’t access the socket.
• Forgetting that /var/run is cleared on reboot. If you create a custom subdirectory there, you need to recreate it on boot. Use a systemd RuntimeDirectory directive to handle this automatically.
• Using a relative path for the socket. Always use an absolute path like /var/run/myapp/gunicorn.sock.
• Not setting the umask, so the socket is world-writable. That lets any local user connect to your Gunicorn instance.
• Mixing up the socket path in Nginx. A missing slash or a typo will cause a 502 Bad Gateway.

Tips

• Use a dedicated system user for Gunicorn, e.g., gunicorn, and make the web server user a member of the same group. This keeps permissions tight.
• If you use systemd, add RuntimeDirectory=myapp to your service file. This creates /run/myapp automatically and sets ownership to the service user.
• Check the socket file with ls -l /path/to/gunicorn.sock. It should show srwxrwx--- if permissions are correct.
• For debugging, you can use curl --unix-socket /path/to/gunicorn.sock http://localhost/ to test Gunicorn directly without the web server.
• If you need to reload Gunicorn, send a HUP signal: kill -HUP $(cat /var/run/gunicorn.pid). The socket file remains intact.

Troubleshooting

• 502 Bad Gateway from Nginx. This usually means Nginx can’t connect to the socket. Check that Gunicorn is running (ps aux | grep gunicorn), the socket file exists (ls -l /path/to/socket), and the path in Nginx matches exactly. Also check Nginx error logs: sudo tail -f /var/log/nginx/error.log.
• Permission denied when connecting. Look at the socket file’s permissions and ownership. The web server user must have read/write access. Try sudo chown www-data:www-data /path/to/socket (if you use www-data) and set umask to 007.
• Socket file doesn’t appear. Gunicorn may have failed to start. Check the Gunicorn logs: sudo journalctl -u gunicorn. Also verify the directory exists and is writable by the Gunicorn user.
• Socket file is left after Gunicorn stops. That’s normal; it’s a file. When Gunicorn starts again, it will overwrite it. If you get an “address already in use” error, remove the stale file: sudo rm /path/to/gunicorn.sock.
• Nginx returns 404 instead of your app. The proxy is working, but the request path may be wrong. Ensure your Gunicorn app is mounted at the correct root. Check your Nginx location block.

Frequently Asked Questions

What is the difference between a socket file and a TCP port?

A socket file is a local file that only works on the same machine. A TCP port listens on a network interface and can accept connections from other machines. Sockets are faster and more secure for local communication because they don’t expose a network port.

Can I use a socket file with Apache?

Yes. Apache can proxy to a Unix socket using mod_proxy. The directive is ProxyPass / unix:/path/to/gunicorn.sock|http://localhost/. Make sure mod_proxy and mod_proxy_http are enabled.

How do I change the socket file location?

Stop Gunicorn, edit the --bind argument (or the systemd service file), then restart. Also update the web server configuration to point to the new path. Remember to create the new directory and set permissions.

Is it safe to put the socket in /tmp?

It’s generally not recommended because /tmp is world-writable and any user can create files there. If you must use /tmp, create a subdirectory with restricted permissions, like /tmp/gunicorn with mode 770 and ownership set to the Gunicorn user and group.

Why do I get a 502 error after restarting Nginx but Gunicorn is running?

This often happens because the socket file is missing or the path is wrong. Check if the socket file exists. If it doesn’t, Gunicorn may not have started correctly. Look at the Gunicorn logs. Also, ensure Nginx has permission to access the directory containing the socket.

Can I use both a socket and a TCP port at the same time?

Yes, you can run multiple Gunicorn workers with different binds, but it’s not common. You might do this to expose a health check on a local port while serving traffic through the socket. Just start two Gunicorn instances or use multiple --bind options (Gunicorn supports multiple binds).

Related

• Backup D Drive? How to Back Up Any Drive in Windows
• Doxxed Staff or Volunteers: What to Do
• App Corrupted After Mac Cleanup? Fix It