Installing the MapServer CGI Program and the Tutorial

Before you can actually go through the tutorial, you'll need to make sure you have your web server running and the MapServer CGI program (mapserv or mapserv.exe) installed in your "cgi-bin" directory. For those working in Microsoft Windows environment, it is recommended that you use the MapServer for Windows (MS4W) package developed by Gateway Geomatics. This is a complete web mapping environment for Windows and includes the Apache web server, GDAL, PROJ, MapServer, and all required libraries and useful utilities.

To install the tutorial under MS4W, simply unzip the archive to C:\ (or whichever drive MS4W is installed) and restart the web server. The tutorial files will be installed under \ms4w\apps\tutorial and an Apache configuration snippet will be installed as \ms4w\httpd.d\httpd_tutorial.conf.

For those who are already familiar with web programming, you can also try to compile MapServer yourself. Windows developers can compile MapServer by following the Compiling on Win32 howto. If you don't have a compiler or don't want to waste precious time compiling MapServer (and libraries), just download from one of the sites mentioned above.

For Unix and Unix-like operating systems, you can search google for binary distribution for your particular platform. If nothing turns up, you can always ask the MapServer-Users mailing list if such binaries exist. If all else fail, you'll have to compile MapServer and the associated libraries. The compilation and installation how-to for Unix is available at

Assuming you've got the MapServer CGI program, follow the steps below to install: (note that MS4W users already have the following configured, and can proceed to the tutorial)


If compiled in Unix, just copy the binary "mapserv" to your "cgi-bin" directory. On a locally compiled Apache server this will be on "/usr/local/apache/cgi-bin/" or /usr/local/apache2/cgi-bin". If your web server comes as part of your OS distribution, look for the "cgi-bin" directory or consult your OS's documentation.


If you compiled on Win32 platform, copy the binary "mapserv.exe" to your "cgi-bin" or "scripts" directory. If you compiled the projection support for MapServer, copy the contents of "proj-4.4.7\nad" subdirectory to "C:\Proj\nad". You'll also need to copy all your supporting libraries to a directory that's part of your system PATH. This would typically be "C:\Windows\System" or "C:\Winnt\System32" but you can always add a different directory in your system (not user) path. If your web server is Apache, the "cgi-bin" directory is typically in "C:\Program Files\Apache Group\Apache\cgi-bin". If you are using Microsoft IIS, the "cgi-bin" directory is typically called "scripts" and is located in "C:\Inetpub\scripts". As with Unix, consult your web server's documentation for more information about "cgi-bin" and CGI programs.


If you are using Win32 binaries downloaded from the MapServer web site, unzip the package to "C:\MapServer". From "C:\MapServer" copy "mapserv.exe" to your "cgi-bin" directory. In Apache this would typically be "C:\Program Files\Apache Group\Apache\cgi-bin" and in Microsoft IIS it is "C:\Inetpub\scripts". Copy the files from "C:\MapServer\lib" to C:\Windows\System or C:\Winnt\System32, whichever is appropriate for your Windows version. (Alternatively, you can edit your system PATH to include "C:\MapServer\lib". In this way you don't have to copy the library files to your system directory.) Move "C:\MapServer\Proj" to "C:\Proj". This is required for projection support. As with Unix, consult your web server's documentation for more information about "cgi-bin" and CGI programs.


Test to make sure that your MapServer CGI program is working. With your web server running, open this URL on a web browser: http://localhost/cgi-bin/mapserv? (on *nix) or http://localhost/cgi-bin/mapserver.exe? or http://localhost/scripts/mapserver.exe? (on Windows). You should get the following message:

No query information to decode. QUERY_STRING is set, but empty.

This means that MapServer is working but you haven't supplied it with anything to process. If you've gotten this far and you've got a different message than above, the first thing to do is to check your error log and see what cause the message to appear. This typically means that you are missing your library files (dll's). Rectify the problem if you can, or check the MapServer FAQ. Failing that, check the MapServer Users mailing list archives, and if the archive isn't helpful, send an e-mail to the MapServer Users mailing list (you must be subscribed to send e-mail to the list).


If you downloaded a copy of the tutorial, change the name of "mapserv" or "mapserv.exe" to "mapserv50" or "mapserv50.exe". The other option is to change each occurence of "mapserv50 "or "mapserv50.exe" back to "mapserv" or "mapserv.exe" in the example files--a very tedious process. This tells you that you can rename the MapServer CGI binary to whatever you want. It isn't recommended but if you run several versions of MapServer on the same machine, you really don't have a choice.


If you downloaded the MapServer tutorial, the easiest way to install it is to unzip the archive to your web server's document root directory--that's the "htdocs" directory in Apache or "C:\Inetpub\wwwroot" in IIS. You will then have to edit your html files to change every occurence of "map=/data/projects/tutorial/example*.map" to "map=/your/htdocs/directory/tutorial/example*.map" (Example: for example1-1.html, you'd change the occurence of "map=/data/projects/tutorial/" to "map=C:/Inetpub/wwwroot/tutorial/") The "*" means change whatever character/s follow after "example". You can make this changes as you go through the examples.


You need to make a "tmp" directory and the easiest way is to create "tmp" directory within Apache's "htdocs" directory or IIS's "wwwroot" directory. You want to make sure that your web server user account (that's usually "nobody" in Unix and "IUSR_MACHINENAME" in IIS--MACHINENAME is the name of your computer). For security, You also want to make sure that users don't have execute permission in this directory. (In Unix and while working as "root", run the commands "chmod a+w /your/htdocs/directory/tmp" and "chmod a-x /your/htdocs/directory/tmp". In Windows, you can use IIS management console to change the permissions.) You will then need to change the value of every occurence of the IMAGEPATH mapfile keyword from "/data/tmp/" to "/your/htdocs/directory/tmp/" (or in Windows, "C:/your/htdocs/directory/tmp" or "C:/Inetpub/wwwroot/tmp").

If you followed the directions up to this point you can now begin your journey into the MapServer realm... Good luck!

Go to the tutorial   |   Download the tutorial


Created by Pericles S. Nacionales
Maintained by Jeff McKenna, GatewayGeo
Last updated: 2021-11-19