Use CGI Scripts with Apache on Ubuntu 26.04

Before you start

Commands that start with sudo need an account with administrator (sudo) rights, and Ubuntu asks for your password the first time.

If you use WSL, systemd (the service manager that starts Apache) must be running in your Ubuntu instance for the systemctl commands to work. If they fail, use a virtual machine instead.

Install Apache2

Skip this section if Apache2 is already installed and serving its default page.

Install the package

1. Open your Ubuntu terminal.
2. Update the package list. This requires administrator rights.
   

   🐧Bash / Shell

   Copy

   sudo apt update

3. Install Apache2. This requires administrator rights.
   

   🐧Bash / Shell

   Copy

   sudo apt install -y apache2

4. Check that the service is running.
   

   💻Code

   Copy

   systemctl status apache2

   
   You should see active (running) in green. Press q to leave the status screen.

Enable the CGI module

Ubuntu’s Apache uses the event MPM (the part of Apache that handles connections in threads). With that setup, CGI needs cgid, a version of the CGI module built for threaded Apache. Turn it on as shown below.

Turn on cgid and restart Apache

1. Enable the module. This requires administrator rights.
   

   🐧Bash / Shell

   Copy

   sudo a2enmod cgid

   Ubuntu prints a message saying the module is enabled, or already enabled.
2. Restart Apache so it loads the module. This requires administrator rights.
   

   🐧Bash / Shell

   Copy

   sudo systemctl restart apache2

Ubuntu’s default setup already maps the /cgi-bin/ URL to the folder /usr/lib/cgi-bin. Once cgid is on, that folder works with no extra configuration. You can write your first script there.

Create and test a CGI script

A CGI script must print an HTTP header first, then a blank line, then the page content. If the header is missing, Apache returns a 500 error.

Write a test script

1. Create a new file in the CGI folder. This requires administrator rights.
   

   🐧Bash / Shell

   Copy

   sudo nano /usr/lib/cgi-bin/test.cgi

2. Type or paste this script:
   

   💻Code

   Copy

   #!/bin/bash
   echo "Content-Type: text/html"
   echo ""
   echo "<html><body>"
   echo "<h1>CGI is working</h1>"
   echo "<p>Server time: $(date)</p>"
   echo "</body></html>"

3. Press Ctrl+O, then Enter to save.
4. Press Ctrl+X to close nano.

Make the script executable

Apache can only run a file that has the execute permission. Give the script that permission so Apache can run it.

1. Set the permissions. This requires administrator rights.
   

   🐧Bash / Shell

   Copy

   sudo chmod 755 /usr/lib/cgi-bin/test.cgi

2. Open a browser on the same machine, or on your Windows PC if you use WSL, and go to:
   

   💻Code

   Copy

   http://localhost/cgi-bin/test.cgi

   For a remote server, replace localhost with the server’s address, for example 192.0.2.10.
3. Look for the heading CGI is working and the current server time.

Run CGI scripts from a different folder

Use this method if you want scripts next to your website files instead of in /usr/lib/cgi-bin. You tell Apache that one folder may run programs and which file extensions count as scripts.

Create the folder and the configuration

1. Create the folder. This requires administrator rights.
   

   🐧Bash / Shell

   Copy

   sudo mkdir /var/www/html/cgi

2. Create a configuration file. This requires administrator rights.
   

   🐧Bash / Shell

   Copy

   sudo nano /etc/apache2/conf-available/my-cgi.conf

3. Add these lines:
   

   💻Code

   Copy

   <Directory /var/www/html/cgi>
       Options +ExecCGI
       AddHandler cgi-script .cgi .py
   </Directory>

   
   Options +ExecCGI allows programs to run in the folder. AddHandler tells Apache that files ending in .cgi or .py are scripts.
4. Save the file with Ctrl+O, Enter, then close nano with Ctrl+X.
5. Enable the configuration. This requires administrator rights.
   

   🐧Bash / Shell

   Copy

   sudo a2enconf my-cgi

6. Check the syntax before you restart.
   

   🐧Bash / Shell

   Copy

   sudo apache2ctl configtest

   The output should end with Syntax OK. If it shows an error, reopen the file and fix the line it names.
7. Restart Apache. This requires administrator rights.
   

   🐧Bash / Shell

   Copy

   sudo systemctl restart apache2

Add and test a Python script

1. Create the script. This requires administrator rights.
   

   🐧Bash / Shell

   Copy

   sudo nano /var/www/html/cgi/hello.py

2. Add this code:
   

   💻Code

   Copy

   #!/usr/bin/python3
   print("Content-Type: text/html")
   print()
   print("<h1>Hello from Python CGI</h1>")

3. Save and close the file.
4. Make it executable. This requires administrator rights.
   

   🐧Bash / Shell

   Copy

   sudo chmod 755 /var/www/html/cgi/hello.py

5. Browse to http://localhost/cgi/hello.py. You should see Hello from Python CGI.

Fix a 500 Internal Server Error

A 500 error means Apache found the script but could not run it. The error log usually names the cause.

1. Open the Apache error log to see why the script failed. Read the last lines, which hold the newest entries. This requires administrator rights.
   

   🐧Bash / Shell

   Copy

   sudo tail -n 20 /var/log/apache2/error.log

2. Look for Permission denied. If you see it, run chmod 755 on the script again.
3. Look for malformed header or End of script output before headers. If you see either, make sure the script prints Content-Type first, followed by a blank line.
4. Look for bad interpreter. If you see it, check the first line of the script (the line that starts with #! and names the program that runs it) for a wrong program path or Windows line endings.

Windows line endings are a common trap if you write the script in Notepad and copy it over. Linux treats the hidden carriage return (a character Windows adds at the end of each line) as part of the command, so the script fails. Remove it with this command. It requires administrator rights if the file sits in a protected folder.

sudo sed -i 's/\r$//' /usr/lib/cgi-bin/test.cgi

Undo the changes

1. Disable the custom folder configuration, if you created it. This requires administrator rights.
   

   🐧Bash / Shell

   Copy

   sudo a2disconf my-cgi

2. Disable the CGI module. This requires administrator rights.
   

   🐧Bash / Shell

   Copy

   sudo a2dismod cgid

3. Restart Apache. This requires administrator rights.
   

   🐧Bash / Shell

   Copy

   sudo systemctl restart apache2

What to do next

If a script still fails after the checks above, run the command sudo apache2ctl configtest again and read the error log while you reload the page. When CGI works, the next task is usually running PHP, which Apache handles through its own module rather than CGI.