Summary: How to make clean urls (Old version)

New page: CleanUrls

Categories: Administration

Questions answered by this recipe

There is a new version of this page under CleanUrls


This recipe deals with how to get rid of that "pmwiki.php" part in the URLs that lead to a PmWiki site.

That is, PmWiki will be at URLs like


instead of





This page currently deals with Apache 1.3/2.0 in conjunction with mod_rewrite.

This page won't help you if you are using a different WWW server (such as Internet Information Server, Xitami, or Zope). It also won't help you if somebody else is in control of the Apache installation and refuses to install or activate mod_rewrite for you, or has Apache configured in a way that your .htaccess files are ignored.

Technique 1: .htaccess and mod_rewrite

Use this technique if you cannot (or don't want to) modify your main Apache configuration files (httpd.conf et al.).

All changes are made in the PmWiki installation directory (i.e. the directory that contains pmwiki.php), which is supposed to be in /DocumentRoot/path/to/wiki, and have URL http://some.domain/path/to/wiki/.

config.php Edit:

To make PmWiki display the shorter URLs, you'll have to set

  $ScriptUrl = 'http://some.domain/path/to/wiki';

in config.php (no trailing slashes).

If you are using Attach:file.ext Δ and so on, don't forget to set the other variables like $PubDirUrl or $UploadUrlFmt as descibed by LecHo? below. Otherwise some links won't work!

On its pages, PmWiki will normally generate query-style URLs of the form http://some.domain/path/to/wiki/pmwiki.php?n=Group.Page. To make it generate path-style URLs like http://some.domain/path/to/wiki/Group/Page, set

  $EnablePathInfo = 1;

wiki root edit:

First, create or change a file named index.php so that it reads:

  <?php include 'pmwiki.php';

This will make sure that URLs like


will automatically call pmwiki.php. (This should actually work with all servers.) This step isn't strictly necessary, but it's a safety net in case that a URL like the above makes it through the rewrite engine without being rewritten.

I prefer to include this line in .htaccess instead:
DirectoryIndex pmwiki.php
This gives you a clean url for the site root.
In this case you have to omit the first rewrite rule though.
If it doesn't work, change the <Directory> section in http.conf:
AllowOverride Indexes
I think the potential AllowOverride complexities make DirectoryIndex a less useful solution. Besides, the index.php trick always works, so why bother with .htaccess in the first place?
Joachim Durchholz September 28, 2005, at 03:05 PM


After that, create or change a file named .htaccess (in the directory of your index.php) so that it reads:

  Options +FollowSymLinks
  RewriteEngine on

  # Redirect browsers that use an empty URL
  # to the default URL.
  RewriteRule ^/?$ http://some.domain/path/to/wiki/dir/Main/HomePage [R=permanent,QSA,L]

  # Map URLs that start with anything but a lower-case letter to pmwiki.php.
  # The remaining URLs are left to the default map-to-filesystem routine of Apache.
  RewriteRule ^([^/a-z].*) pmwiki.php?n=$1 [QSA,L]
Hi, the Options +FollowSymLinks option is, while arguably senseful, not necessary, and in several apache configuration this leads to a 500 Internal Server Error. So, if you like this receipee's idea, but it just doesn't work, leave that first line away. --SzSz?
I would like to support the advice tparlin is giving at the bottom of this page - I also had to use an additional slash to make it work, i.e. this last line looks like this in my config:
RewriteRule ^([^/a-z].*) /pmwiki.php?n=$1 [QSA,L]
If setting up clean URLs for a field in a wikifarm, the .htaccess file should be in the field's directory. Doing so eliminated my 404 errors for pages other than the homepage.
If you see "Options not allowed here" or "RewriteEngine not allowed here" change the <Directory> section in http.conf:
AllowOverride Indexes Options FileInfo
You may need to add a RewriteBase directive if you get a 404 error when accessing the clean URLs
RewriteBase /logical/path/to/wiki

You can leave out the comment lines that start with a hash mark #, but it's probably a good idea to leave them in anyway: if you or somebody else wants to modify the configuration later, the comments will help in understanding what the directives do.

The first two directives enable rewrite processing. (Yes, you need FollowSymLinks - the rationale is that if symlinks are not allowed, the far more powerful abilities of mod_rewrite shouldn't be allowed either.)

The first RewriteRule redirects http://some.domain/path/to/wiki/dir and http://some.domain/path/to/wiki/dir/ to the start page of the wiki. (Feel free to select a different group and page than Main/HomePage if you wish.) The final [R] option establishes the rewrite in a way that the user's browser is notified and can update the address bar.

The second RewriteRule takes the URL and inserts pmwiki.php/ at the right place. It does not apply to URLs that begin with a lowercase letter (because these are reserved for URLs that contain all sorts of auxiliary information: pub/skins, pub/css, favicon.ico, and last but not least pmwiki.php itself). It also avoids rewriting URLs that start with a slash, since sometimes the rewrite rule will be fed with absolute directory paths (which are guaranteed to start with a slash - on a Windows system, you should probably do something like RewriteRule ^([^\\a-z][^:\\]?.*) pmwiki.php/$1 to capture UNC names and names starting with a drive letter).

The second RewriteRule could also be written as

  RewriteRule ^([^/a-z].*) pmwiki.php?n=$1 [QSA,L]

This might be necessary if path-style URLs don't work (it seems to be possible to misconfigure Apache and/or PHP in this way). The QSA option is necessary to preserve ?action=edit and similar things - this tells mod_rewrite to add the ?n=$1 string to the URL instead of replacing everything after the first question mark.


If there is some problem with the rewrite rules, turn on rewrite logging (RewriteLog /path/to/rewrite.log) and set the rewrite log level to 9 (RewriteLogLevel 9) if you can. This will tell you in excruciating detail when and what mod_rewrite is doing, and give you hints where the problem actually is. Rewriting is an iterative process, and if you get an error message, it may be working on a URL that was already rewritten to something not even remotely similar to what you'd expect.

To switch on rewrite logging, you need access to httpd.conf. If you don't have that (that's quite the normal case), set up a test installation on your personal computer. For a Windows box, you can get a quite painless install from

Note 1. This recipe will work even if you have a wiki-only site (i.e. if pmwiki.php is in the document root, and users are expected to use URLs like http://some.domain/Group/Page).

Note 2. To make PmWiki display the shorter URLs, you'll have to set

  $ScriptUrl = 'http://some.domain/path/to/wiki'

in config.php (no trailing slashes). To make PmWiki generate path-style URLs (i.e. .../Group/Page instead of ...?n=Group.Page in the pages that it outputs, set

  $EnablePathInfo = 1;

Joachim Durchholz April 01, 2005, at 02:25 PM

Technique 2: "Alias"

Use the aliasing feature of Apache. Edit the httpd.conf file, and add a line like

 Alias /wiki "/var/www/html/pmwiki.php"

where you would of course specify the correct path to pmwiki.php. Then put

 $EnablePathInfo = 1;
 $PubDirUrl = "";

in config.php.

adding the correct path to the "pub" directory with out the pmwiki.php. Alias messes up the links into the pub directory when pmWiki tries to auto sence that.

Note that this requires write access to the httpd.conf file (since Alias directives aren't allowed in directory or .htaccess context). Most webspace providers disallow this, since it's easy to kill Apache by providing invalid content in httpd.conf. -- JoachimDurchholz 22 Mar 2005

Technique 3: Apache Configuration

Again, this requires write access to httpd.conf.

  • Enable mod_rewrite LoadModule rewrite_module modules/
  • Add a Directory directive for your pmwiki directory (this is where your .htaccess file exists).
  • Specify AllowOverride Options, or Apache will not process options found in the .htaccess file.
  • Specify Options FollowSymLinks
  • Don't forget to restart Apache

Questions & Discussion

I couldn't get the directions on step 2 to work on my commercial webhost that does give me access to .htaccess file, but not a full path to the folders I'm given. I got it working when I changed the .htaccess file in the root of the pmwiki installation to look like below - with no path to pmwiki at all and following all other directions.

     RewriteEngine on
     RewriteRule ^([A-Z].*) pmwiki.php?n=$1 [L,qsappend]
     RewriteRule ^$ pmwiki.php [L,qsappend]


You can easily discover the pathnames used on your webhost by putting up a simple php script that looks like
The very bottom of the huge mass of output should list all the relevant directories.

My webhoster also doesn't allow any .htaccess file changes. Is there a standard workaround to this problem? If the solution isn't all that complex and works in most cases, it might be a good idea to add it to the page. I could imagine many others are in the same situation as I am.

You're out of luck. Change the webhoster or live with the long URLs. -- JoachimDurchholz 22 Mar 2005

This seems like a long shot, but is there a way to configure PmWiki to use the 'Main' namespace implicitly - but hide it from the urls?

You need a RedirectMatch that maps URLs with "Main" in them to the plain URLs (PmWiki will generate those URLs). You'll also need a RewriteRule that matches only those URLs that don't contain the group name and inserts a "Main/" at the appropriate place. (Results from RedirectMatch are shown in the address bar of the browser, results from RewriteRule aren't.) -- JoachimDurchholz 22 Mar 2005

Jan 24, 2005

I tried to set this up on a local wiki. Our admin was setting up a certificate so that the wiki would be accessible via https. However it seems that when using 'Clean form' the links point back to HTTP server vs HTTPS. Any way to fix or address this? Thank you.

-- Gennady
Sure, just set the value of $ScriptUrl explicitly to use a relative uri (i.e., to omit the leading http://server part). --Pm

Tried the above howto and it works fine. But uploading doesn't work anymore, I had to change the upload.php and change the action to ~/pmwiki.php -- UH

Just a Tip to easily define the directories

    $EnablePathInfo = 1;
    $BaseUrl = 'http://'.$_SERVER[HTTP_HOST];
    $ScriptUrl = $BaseUrl.'/~me/pmwiki';
    $PubDirUrl = $BaseUrl.'/~me/pmwiki/pub';
    $UploadUrlFmt = $BaseUrl.'/~me/pmwiki/uploads';

should work fine --Isidor

Note: This does not work with Windows 2K. -Doug Parker
Is it that it doesn't work with Windows 2K, or that it doesn't work with IIS? Many people have Apache running under Windows, where this ought to work...? --Pm

Note on localization - this does not seem to work with swedish characters, i.e. Å, Ä, Ö. Has something to do with http?

My guess is that this was a problem with an old version of the recipe where URLs using uppercase lessers in the A-Z range were taken to be wiki pages. The current version considers everything not in the a-z range to be a wiki page, so pages with umlauts and other "funny characters" in their name should work. Joachim Durchholz April 01, 2005, at 02:25 PM

I really hate how pmwiki handles URLs. This helps, but is there a way to get rid of the annoying /Main/ part and possibly also avoid capitalization of every sentence in URLs as it looks incredibly stupid in any other language than English.

Propose an alternative url syntax. --Pm
Use the ?n=Group/Page syntax. Joachim Durchholz April 01, 2005, at 02:25 PM

I followed all the instructions and it didn't work... Finally I realized my .htaccess file was being ignored. When I checked my httpd.conf I found the following:

AllowOverride None

which completely disables .htaccess files. That is the default configuration on Fedora Core 1 Linux with Apache 2.0.50. Changing that line to:

AllowOverride All

and restarting httpd fixed the problem.

--PhilHollenback 2005-3-21

You've jeopardized security. I strongly recommend you only do that in <directory> statements which cover the pmwiki installation dir.

Worked first time for me. However, now all the default PmWiki pages which I planned to leave there have links in the old format :b Any easy workaround? --Riccardo G. 2005-3-30

Shouldn't be any workaround needed -- PmWiki will still continue to recognize the old-format links. --Pm

URL Rewriting under Apache 1.x on Win32 (the one from, I can't speak for the version) doesn't work - see:

Using Apache 2.0+ (as per the link above) is apparently the only solution for those stuck with Win32. To quote the last entry in the bugzilla issue above:

Whoops. Ok, this has simply got to be marked won't fix.
As I said 15 months ago - it is simply NOT possible to straighten this out in Apache 1.3/Win32. Nothing has changed, or will change, in that answer. If you don't like the behavior (certainly I don't :-) then upgrade to 2.0.

AllowOverride All is still required in the httpd.conf file to allow .htaccess files to work.


the problem is that Windoze Apache 1.3 converts all parts of a URL that appear to be a directory/file path to lower case before the URL is processed by the rewrite engine. this means that rewrite rules which depend on a leading capital letter will not work. in general, if the page URL ends with '.../Group/Page', interCaps will (sometimes?) be lost in the group name, and if it ends with '.../Group.Page they are lost on the page name as well. fwiw, --bang June 04, 2005, at 09:01 AM

As at 2.0 b32 an extra command (and the index.php trick above) needs to be used to allow searching to work:

RewriteEngine on

RewriteCond %{QUERY_STRING} ^$
RewriteRule ^/?$ http://wiki.server/path/Main/HomePage [R=permanent,L]

RewriteRule ^([^/a-z].*) pmwiki.php?n=$1 [QSA,L]

Without this you will get a url like so:

With it you get a url like this:


Perhaps this ought to be placed in the instructions above - this seems to me a fairly important fix... Jon?

The same still applies in Apache 2.0.54. stormspotter

For this method to work, Apache has to be configured to support rewriting. Add this to your httpd.conf:

LoadModule rewrite_module /path/to/your/apache2/modules/

And make sure, the pmwiki directory allows rewriting by adding the AllowOverride All statement mentioned above into that file.

On my machine, I run debian which puts the apache modules into /usr/lib/apache2/

Debian uses the following mechanism: /etc/apache2/ contains two directories with the names mods-available (all available modules) and mods-enabled. To enable an available module, simply symlink the corresponding file in mods-available into the mods-enabled directory: Debian's apache startup takes care of loading the module (You will still have to add the AllowOverride All directive though).

Orm Finnendahl?

On a site hosted with Apache 2, I'm having an annoying problem. The url rewriting works fine, except when I follow a link, there is an extra '/' in the url. For example, you're in the WikiSandbox and you want to go back to the main page, so you click the link and it will take you to instead of

I know it's fine to leave it like this, as it's working, but it doesn't look as 'pretty' as I'd like it to. Especially when I'm already using mod_rewrite to clean up the url.

Any suggestions for how I can fix this?


I forgot to mention, if you want to see the problem on the site I have under development right now, you can go to . stormspotter

 $ScriptUrl = '';  


 $ScriptUrl = '';


sigh... Looks like I overlooked the obvious again. Thanks, Anno. stormspotter

I cant get this to work on my site. I got the path style URLs to work but it still puts index.php or pmwiki.php in the url. -- Austin ( )




It took me a couple of days, but now it works ...

I was told to use a RewriteBase function in addition ...

my final .htaccess:

#my pmwiki.php is located at http://www.some.domain/~username/MyTry/pmwiki.php
#Options +FollowSymLinks   - was not supported - always generated error
RewriteEngine on
RewriteBase /~username/MyTry/
RewriteCond %{QUERY_STRING} ^$
#and the stuff mentioneed at the beginning
RewriteRule ^/?$ http://www.some.domain/~username/MyTry/Main [R=permanent,QSA,L]
RewriteRule ^([^/a-z].*) pmwiki.php?n=$1 [QSA,L]

Additionally it's don't forgrt to add to your config.php a couple of lines proposed by Isidor :-)

$EnablePathInfo = 1;
$BaseUrl = 'http://www.some.domain';
$ScriptUrl = $BaseUrl.'/~username/MyTry';
$PubDirUrl = $BaseUrl.'/~username/MyTry';
$UploadUrlFmt = $BaseUrl.'/~username/MyTry/uploads';

otherwise you might find some links not working on your webpage (especially attachements - since the 'uploads' dir got translated wrong...)

Cheers! LecHo

My Solution:

Create .htaccess file in root directory of wiki that looks like so:

DirectoryIndex pmwiki.php
RewriteEngine on
RewriteCond %{QUERY_STRING} ^$
RewriteRule ^/?$ [R=permanent,QSA,L]
RewriteRule ^([^/a-z].*) /pmwiki.php?n=$1 [QSA,L]

I had to add an extra "/" in front of pmwiki.php


If you are using "?" style URLs, then you need to use:

RewriteRule ^([^/a-z].*) pmwiki.php?n=$1 [QSA,L]

If you are using "slash" style URLs ("$EnablePathInfo = 1;" in config.php) then this line needs to be:

RewriteRule ^([^/a-z].*) pmwiki.php/$1 [QSA,L]

Leastways, that's what I needed to do to make it work.


I'm pretty sure you can do this with IIS, you just need a whole different configuration (i.e. not .htaccess). I'm running Win2003 w/ IIS 6. I'll let ya'll know how things work out, but if anybody has suggestions, I'll be listening as I'm working. BTW, does anybody know how to do a masked redirect using IIS? That would essentially solve this problem, then all you have to do is use aliases.

-Michael Ansel

The following .htaccess works for 1and1 shared hosting (Apache 1.3.33, PHP 4.3.10):

Options +FollowSymLinks
RewriteEngine on

# RewriteBase is the directory where pmwiki.php lives
RewriteBase /stw

# Redirect browsers that use an empty URL to Main.HomePage
RewriteRule ^/?$  /stw/Main/HomePage [R=permanent,QSA,L]

# Map URLs that start with anything but a lower-case letter to pmwiki.php.
# The remaining URLs are left to the default map-to-filesystem routine of Apache.
RewriteRule ^([^/a-z].*) pmwiki.php?n=$1 [QSA,L] 


I too, found this recipe to be cumbersome. So here is my solution step by step.

Let's assume:

  1. DocumentRoot is /www
  2. PmWiki installed at /www/pmwiki
  3. Upload directory at /www/pmwiki/uP

Let's say that you would like your URLs to look like:


My /www/.htaccess file is:

Options -Indexes
ErrorDocument 403 /noindex.html
RewriteEngine On
RewriteRule ^/?$ [R=permanent,QSA,L]
RewriteRule ^wiki$ [R=permanent,QSA,L]
RewriteRule ^wiki/uP/([^/a-z].*) /pmwiki/uP/$1 [QSA,L]
RewriteRule ^wiki/([^/a-z].*) /pmwiki/pmwiki.php?n=$1 [QSA,L]

Now, in my /www/pmwiki/local/config.php file:

$ScriptUrl = '';
$PubDirUrl = '';
$EnablePathInfo = 1;
$EnableUpload = 1;
$UploadDir = 'uP';

I also have:

<?php include 'pmwiki/pmwiki.php'; ?>

in my /www/index.php, but maybe that's not required (?).

Update: Online updates to SUSE 9.3 for Apache2 and/or php5 causes all of this to SEGV. I reverted back to the original SUSE 9.3 versions until I can diagnose what is wrong. Using strace, ltrace and logging levels did not reveal anything. Removing the rewriting stuff altogether worked. I suspect something is wrong in the php5 update when the URL is rewritten. Seems to be SEGVing in php5 (but I could be wrong).


SuSE managed to bundle Apache modules that are mutually incompatible. I had to move mod_rewrite to the end of the module list to make it work again (and remove another module, but I forgot which - iconv I think).

Hi all! I tried all the solutions given here but nothing worked. Since I've installed also Dokuwiki I decided to try the solution I used for that wiki, and yes, it worked :-)

Here is my .htaccess (my server runs Apache, I don't know if this works with other softwares):

  RewriteEngine on
  RewriteBase /pmwiki
  RewriteRule ^$                        pmwiki.php  [L]
  RewriteCond %{REQUEST_FILENAME}       !-f
  RewriteCond %{REQUEST_FILENAME}       !-d
  RewriteRule (.*)                      pmwiki.php?n=$1  [QSA,L]
  RewriteRule ^index.php$               pmwiki.php

Of course pmwiki is the main pmwiki directory, and you have to modify your config.php to enable cleanurls. Hope that helped.


Yes! This worked for me when nothing else did. (Using a free account).

But after that, I could not upload and attach. Apparently pmwiki was looking for my uploads directory to be one level higher (i.e. it was not including /pmwiki/ in the path). I tried explicitly stating the path in my config.php by adding $UploadUrl='http://~me/pmwiki/uploads';, but that did not work. But then I found Isidor's tip and changed the entry to $UploadUrlFmt = $BaseUrl.'/~me/pmwiki/uploads'; and that solved it.

Thank you Gesu and Isidor


Before Google Sitemaps will provide full statistics for a site it wants you to prove that you have admin access to the server. It does this by asking you to upload a file named googlexxxx.html (where xxxx is a unique ID). It then checks your server to see if it can request this file, and it also checks to see that a non-existent file produces a 404. The non-existent file it checks for is named GOOGLE404probexxxx.html. Since this starts with an uppercase letter the URL rewriting of this recipe will instead cause the PmWiki Main/PageNotFound page to be returned and the verification to fail. In order to get the Google verification checks to pass a further rewrite rule is needed, to make sure Google gets a 404 when it requests the non-existent page. The following will suffice, before the others:

  # Rewrite Google 404 probes to a page that will actually give a 404
  RewriteRule ^GOOGLE404 /google404 [QSA,L] 

-- mdkendall

With Apache2 + PHP-CGI + suexec setups getting more popular, here's one pit to fall into:

I found out the hard way that this setup tends to get the environment variables all wrong. The root cause of the problem is that Apache will think that it's the php executable that's the script, not the .php file.

Setting cgi.fix_pathinfo = 1 in the pertinent php.ini fixed the problem. (Note that PHP-CGI ignores Apache's php_value and php_admin_value directives, it's configured using php.ini files.)

Apache's SetEnv directive might have helped, too, but I didn't go that route.

''+How do I set the URL's for subwebs?'+'

I installed pmwiki in - it works - you can go to and click on the link at the bottom of the page that says Wiki Test.

I have a subdomain at - also called

It is hosted on [blocked].

I put the Wiki in - that had the wrong URL on the home page, so I tried to make a Wiki Farm on and a Wiki Field on - by putting field.php in that folder. I had exactly the same error which is this.

The requested URL //Techvangelism/Techvangelism/php/pmwiki/field.php was not found on this server.

i.e. it put instead of - so there is an extra //Techvangelism in the path of all links on the created home page in the Field.

So I need to change a Config file. Netfirms suggests using $ENV{'DOCUMENT_ROOT'}/www for I don't know if I need to make a Config file in or subdomain Do I really need another .htaccess file - when I use chmod or equivalent in FTP program to set permissions? There is a .htaccess file in the local directory of - do I need to have one in the corresponding folder for the subweb. It seems if I could get the path to come out right then things would work.

I am new to PHP and Wiki programming - this is one day into it - so please help me!? Thank you so much if you can solve this path name riddle - Angela Hey