Last updated 25 May 2016.

This page answers the question: How do I apply a patch to a module?

Much of the existing patching documentation on how to apply a patch (see links below) is extremely cryptic and assumes more technical knowledge than some aspiring, but worthy patchers have.

But even those with somewhat lesser technical know-how may want (or need) to apply a module patch from time to time. For instance, there is an important feature that has been developed for your module, but it is still not available in an official release. Or, you have reported a bug in the module, and the module maintainer has asked you to test a patch that fixes it.

This how-to provides a detailed step-by-step guide to applying patches to contributed modules. It is designed for first-time patchers and/or less technical folks who have the need to apply a patch. The how-to specifically relates to applying patches on Windows machines, but the basic information and steps may be helpful for others. It is also written for a localhost (i.e., a development environment, and the particular directory structure follows XAMPP's naming) configuration, but the same steps would apply to a hosted environment as well, if it is a Windows environment. You'll just need to switch the location where some of the steps are executed.

Caution: Patches can break, and even permanently damage your system. Patching is something that should never be done on your production site unless you first have a complete backup of your site, and you have tested that backup: First. Unless you know what you are doing, please only apply patches that are well proven by the Drupal community and/or patches you've been asked by the module maintainer to test.

This guide can't cover every possible situation that you are likely to encounter. You need to develop a solid general understanding of what a patch is and what happens when you apply it. You should always first apply patches to a development environment. Take the time to learn how to set up a development environment. Also, make sure to read through and understand the entire set of instructions provided here before you actually follow the steps.

You can tell a module patch has been "well proven by the community" by either:

  • seeing a notation in the issue queue which states the thread has been "reviewed & tested by the community"
  • and/or

  • reading the associated issue thread and seeing that many people have confirmed successful application of the patch.

If you find a patch that has not been validated by seasoned Drupalers, do not install it, as it may break your system.

What is a Patch?

A "patch file" is a specific kind of file that contains code that is used to modify one or more existing files for a Drupal module. The "patch" command is a Linux command that performs the patching operation. Patching and patch files are not unique to Drupal; they are widely used to modify all sorts of files.

In the context of patch files for Drupal modules, the patch file is normally intended to change existing .module files. The patch file contains lines of code that are either being added to the .module file (indicated by a "+") or being deleted from the .module file (indicated by a "-" sign). As well, each block of lines with +/- signs is preceded and followed by unmarked reference lines that serve to tell the patching program where to insert/delete the lines. If you look at a typical patch file, you will see several such groups of lines - beginning and ending reference lines, plus variable numbers of +/- lines. Each such grouping is called a "hunk." If the patch fails to apply, you will often see "hunk failed" errors.

Patching does not happen in Drupal per se, nor does it happen in Windows. Rather, it is done in Linux (or other Unix flavor) or a Linux emulator. The UnxUtils package also provides a Windows native implementation of the patch command.

Because the "patch" command is a Unix command—not a Drupal command or a Windows command—Windows users need to utilize a tool that allows them to run Unix commands. There are several tools for doing this. This how-to assumes you are using a Linux emulator called Cygwin to apply patches, but you could use one of the other tools instead.

Additional Drupal patching sources

Before trying to apply a patch, we recommend you read some of the other materials available on to help you more fully understand the process. While the patching process itself is quite simple, the changes that occur from applying the patch can be quite complex. Applying patches can be a bit risky, so you want to avoid mistakes and understand what is happening when you apply patches. There is a procedure that one is "supposed" to follow to create a patch. Be aware that the procedure may have been followed properly and it may not have. Also, the procedure allows for two different ways to "roll" the patch. This is why it was recommended earlier that you apply only the patches that have already been "well-proven."

  • Applying patches - This is the Intro page to the existing materials on patching. Most pages here are written for a fairly technical audience.
  • Applying patches manually - This is interesting to read because it helps explain what is actually in a "patch" file. Furthermore, for simple patches, doing them manually might be just as fast as the steps below. If you are going to apply patches manually, you will definitely need to use a plain text editor, such as Notepad++.
  • Apply patches on Windows - This is a cryptically written series of pages for using various tools - Cygwin, GnuWin32, and UnxUtils - for patching.
  • Apply patches on Mac OS - This material looks just as cryptic as the Windows information.
  • Applying patches to core - This provides a link to a useful video that's definitely worth watching, since patching modules and patching core is procedurally about the same. Be aware: the video flashes through the command line steps that are likely to be the most vexing to first timers and less technical folks.

Prerequisite - Install Cygwin

Before you can apply a patch, you need to install Cygwin on your Windows machine. Cygwin is an open source program that is widely used and very safe. It will work on most any Windows machine, including Vista and 64 bit versions.

As described on the Cygwin home page:

Cygwin is a Linux-like environment for Windows. It consists of two parts:

  • A DLL (cygwin1.dll) which acts as a Linux API emulation layer providing substantial Linux API functionality.
  • A collection of tools which provide Linux look and feel.

Visit the Cygwin website to learn more and download the setup.

Cygwin's site provides great information on how to install it. However, if you want to find more information, you may conduct a search with Google or your preferred search engine using keywords "install cygwin." Also, these posts/videos by Drupalers may be of help: Lullabot cygwin installation video (this is for XP, but same approach works with Vista, etc.) and a post at

Cygwin Basics

Once you have installed Cygwin, you will be able to open it like a normal program. However, the program has a cryptic interface and doesn't do anything unless you give it commands. In the hands of novices, using it is like stepping back 20 years on a PC, but it gets the job done (and is actually very powerful if you know what you are doing).

The following commands should be enough to get your patch installed:

  • cd .. - moves you up a level in the directory ('cd' means 'change directory')
  • cd folder_name - moves you down 1 level into folder_name
  • cd folder_x/folder_y - moves you down 2 levels into that folder_y (you can drop down however many levels you want)
  • cd c:/folder_x/folder_y - moves from anywhere to folder_y on the specified path
  • cd - returns you to your default cygwin directory
  • ls - lists the folders and files in the directory you are currently in
  • logout - this is how you get out of cygwin's terminal emulation window

The key initial challenge with cygwin is figuring out where you are within your file directory. Cygwin does give you a hint of where you are with the line it displays above your prompt. To apply your patch, you will want to navigate into the module's folder. This may take you a while to figure out - see step #3 - but the above commands will get you there eventually, especially if you open Windows Explorer and use that to help you move around.

Preparatory steps

Prior to applying the patch, the following steps are highly recommended:

  • Apply the patch to a development environment or test site. Once you are sure that it works, you can apply it to your production environment.
  • Backup your database. Since patches don't always work correctly, there is a possibility that a successfully applied patch may trash your database. A backup is advised.
  • Backup the module files (Note: there is a way that you can have patch create backups of any files it modifies. See instructions below). In case you need to revert to the original version, it may be helpful to have a backup of the module files. You can either copy the entire folder or, if you know the exact files being patched, just those individual files. You can figure out what files are being patched by looking at the .patch file. To do this, open the patch file (preferably in a plain text editor such as Notepad++) and take a look through it to see which files are going to be affected. The patch may have more than one section, depending on whether more than one file is going to be modified. In each new section you will find a couple of lines that specify what file is being changed. The first line should start with --- and then have the name of the file that is being changed. The second line should start with +++ and then specify the name of the file in which the changes were made. For this example, we will assume that only one file (scary_module.module) is being changed. (So, we would make a copy of that file and name it something like scary_module.module.backup. The name you choose is unimportant; it just gives you a way to save a backup.)

Step-by-Step: Patch a Contributed Module

Okay, now we are ready to patch a module. Here are the steps:

  1. Locate the desired patch
    • Navigate to the appropriate issue on
    • Make sure you are choosing a patch that is designed for your version of the module
    • Look through the entire series of comments attached to the issue and choose the most recent, stable patch. A patch may need to go through several iterations.
    • Note that a patch file can be saved in any of several file formats. '.patch' is perhaps the most common, but you may also find patches with '.txt' or other file types. The same procedure applies regardless of the file type - you just need to modify the command shown below accordingly.
    • For illustrative purposes here, we will assume that the module being changed is called 'scary_module' and that the patch being applied is called fix_scary_module.patch.
  2. Right-click the patch and save it to the module's directory for your Drupal install
    • When you right click, you will see an option to 'save link as...' (in firefox or chrome in windows). Choose this and save the file to the right spot.
    • You want to save the patch into the directory in which the to-be-patched module resides. In this example, starting from your Drupal root directory, you would navigate to sites/all/modules/scary_module
    • Use Windows Explorer to confirm patch file is in the right place
  3. In Cygwin, navigate to the module's directory for your Drupal install
    • Until you get the hang of it, this step may take a bit of wrangling to get right. To do this, you typically need to navigate up a few levels to your cygwin HOME directory, then make your way back down into and through your Drupal directory.
    • Open Cygwin and at the prompt, type "ls" to list the files in your current directory.
    • In Windows Explorer, locate the folder these files are in.
    • Using commands listed above, navigate up, across, and down to your module's directory.
    • Or, you can try to jump straight there by fully specifying your path with a command like: cd c:/xampp/htdocs/drupal/sites/all/modules/scary_module Correcting typos in cygwin can be a pain, so type carefully. If you made a typo, you can use the up arrow key to recall the last command you entered at the prompt and then correct your typing mistakes.
    • Confirm you are in the right directory by typing "ls" to list the files and confirm that you see both your desired .module file (scary_module.module) and your .patch file (fix_scary_module.patch) listed.

    You're almost there!

  4. Patch the file. Now you are ready to run the patch command and patch the file.
    • You can execute a test of installing the patch by entering:
      patch -p0 --dry-run < fix_scary_module.patch
      This prints the results of applying the patch without actually making any changes.
    • When ready to do the patch for real, enter one of the following at the Cygwin prompt:
      patch -p0 < fix_scary_module.patch OR
      patch -p0 -b < fix_scary_module.patch
      (Don't enter both commands - just one.) The version with the '-b' option will automatically create backups of any files that the patch modifies.
      Obviously you need to substitute your actual file name in place of our example.
    • If all goes well, you should see something like: "patching file scary_module.module" and nothing else. Depending on how much has been changed, there can be quite a few lines of text output to your screen. You will want to scroll through them to check for any errors. It's rather unsatisfying, but it won't actually say if the patch successfully applied. The absence of errors is as good as it gets. It may also say something like "(Stripping trailing CRs from patch.)" which you can safely ignore.
    • If there were no errors, then you can confirm the patch was applied by opening the .module file (scary_module.module) and looking for some of the new lines that were marked by "+" in the patch file. If those lines are there, then the patch worked and you can go to step #5.
    • If you get things like "Hunk #1 FAILED at 220." then the patch didn't apply properly. "Hunk #1" refers to the first chunk of add/delete lines in the patch file. "220" is the line of the file where the failure occurred. Notify the patch maintainer if you get this error.
    • If you get other errors make sure you executed the steps right. Check the issue queue to see if you missed something.
    • Regardless of what error you get, you will want to revert the changes the patch made before you try to patch again. Go to step #6 and revert back to the original .module version.

    Note: you do not need to run update.php after applying a patch.

  5. See if the patch applied.
    • If the patch appears to have worked, you should now visit your site and reload some pages.
    • First make sure that the site appears to be working normally in all respects.
    • Then check to see if the desired new feature or fix has been enabled and that it does what it was supposed to do.
    • In some cases, you may need to clear cache to see changes.
    • If it works in all respects, then you are good to go and are done.

    If the patch does not appear to do anything, then you should re-read the issue thread to see if you missed anything (a lot of patches simply don't work). If you can't get it working properly, then you need to revert back to the original .module file (step #6) and hope the module developers officially release the feature soon.

  6. Reverting back to the original file.
    • If your patch successfully applied and works, please ignore this step. If your patch either failed to apply (step #4) or appeared to apply, but didn't actually change site behavior (step #5), then you should revert to the original .module version as follows:
    • Go back to your cygwin window.
    • At the module's directory enter:
      patch -p0 -R < fix_scary_module.patch.
    • Alternatively, you can make use of your backup file. Delete scary_module.module and rename scary_module.module.backup to scary_module.module. If you took advantage of patch's ability to make a backup, then just do the same thing, only use the backup that patch created.
    • Visit your site and load a bunch of pages to ensure everything is now working the way it was prior to installing the patch, particularly the module you attempted to patch.
    • In the unfortunate (and unlikely) event that the patch trashed your database, you will need to do a restore from your database backup you created earlier.


  • The above process uses XAMPP for path examples. If you are using something other than XAMPP, please adjust paths accordingly.
  • The actual value needed for the -pN flag to patch may vary depending on your Drupal install. The flag instructs patch to peel off any directories in the diff line near the top of the patchfile made problematic by the structure of your site. Use the --dry-run flag with different values as noted above to get a clean trial run. See the patch manpage for more detail.
  • One patch file can be created to modify multiple files at same time. As long as all the to-be-modified files are in the module folder, the same process above applies.
  • Not all patches are saved as .patch files. You may also see .txt or other suffixes. The patch command will work for any of these, just make sure you use the right suffix in your command.
  • This guide repeatedly refers to the module's directory. It is more accurate to think of it as the project's directory, where the "project" could be a contributed module or theme. The steps to patch a theme are essentially the same.


Terebinth’s picture

Thanks so much. I've been battling with patches for months now. This is the first basic step-by-step instruction I've come across and I patched like a pro!

khosman’s picture

Thanks much for this how-to. I spent all day yesterday spinning my wheels, trying to figure this out. This worked great after figuring out a few more items:

- When first installing cygwin, on the "Select Packages" page you'll need to go to devel > patchutils
and enable the box in column marked "bin." Otherwise you'll get an error when you try to patch the first time saying that cygwin can't find the app.

- To add packages later (after finishing your initial cygwin install), simply run back through the installation by running the initial set up file. (If you forget to select "patchutils" as outlined above, for instance.)

- Moving around your folder structure (using "CD") is different (at least from my perspective) than how I used to do it at a DOS command prompt some 20 years ago. Apparently Windows and UNIX paths are entered differently; you can't use spaces in a file/folder name, etc. See this page for work arounds: Case in point: I had issues trying to navigate to/past my "Program Files" directory/folder because of the space in the name. I had to 'escape the space.'
Here's what worked; I entered: cd /cygdrive/c/Program\ Files
(If this pertains to you, don't forget a space after the "cd" and of course the space before the word "Files")

Again - thanks - my head was going to explode yesterday after downloading myriad apps and surfing across tons of mind-numbing how-tos.

PvO’s picture

Thank you!.
I would like the author of the original post to integrate "Spaces in directories" that keeps 'us' form first trying.....

mkesper’s picture

Hi, use key for command completion. This gets you past those paths, also. :)

kari.kaariainen’s picture

That probably was supposed to read "use <tab> key" ;)

zzrwood’s picture

Very useful and detailed instructions to help people new to the whole patch concept.

Just one thing, you don't need to use the -p0 action (immediately following the patch command) unless the patch file is in a different location than the module.

This means you could simplify:
patch -p0 < fix_scary_module.patch
to be:
patch < fix_scary_module.patch

Cheers from Oz

deeve’s picture

When I try running this on my Windows local machine I get 'patch: command not found' in cygwin - any ideas why this could be?

Edit: I've just realized I hadn't downloaded patch.exe within initial setup! Ran setup again, ticked to install 'Patch' within 'Utilities', re-ran cygwin & presto, it now works!

starapple’s picture

A combined response to zzrwood and deeve: Having installed Patch on Windows 7 Pro, I found that -p0 was not a known command. patch.exe was recognised and executed.

I'd also suggest to Win 7 users to run Cygwin as administrator and make sure that the directory and files to be patched have read write permissions.

MatthiasHH’s picture

deeve, you can solve the issue by updating cygwin and installing patch.exe.

Check your cygwin/bin folder if a file called patch.exe exists.
If not, call the setup again, but from console and add the paramenter "-P patch".

1. Open Windows command line as an administrator.
2. Go to the directory with the file cygwinsetup.exe
3. Type cygwinsetup.exe -P patch

Setup will reinstall cygwin and load the patch module.

theMusician’s picture

This is a great walk-through for those of us new to Linux sysadmin. I know this was written for Windows but the command line instructions work great on any platform.

rogerlightfoot’s picture

I found I had to apply to measures here to make Cygwin work on Windows 7.

Repeated below:

If you are a linux enthusiast and really miss those greps and sed/awks on the windows box, you've probably installed cygwin. You tried running it either by double-clicking the cygwin icon on your desktop or the cygwin.bat file in your "C:\cygwin" directory and got the bash-3.X$ prompt. However, although the pwd or cd commands work, if you try ls, it says:"ls: command not found".

Here is what you need to do to fix it:

Right click on "My Computer" -> Properties -> Advanced -> Environment Variables
Add a new environment variable, called CYGWIN_HOME and set its value to C:\cygwin
Edit the PATH environment variable and add C:\cygwin\bin to it (usually separated by a ';').
Just click okay, exit any command prompts or bash shells (over cygwin) you may have open, and open it again - it'll work!

Note: this assumes that you have installed cygwin at C:\cygwin. If you've kept it someplace else, please modify the above accordingly.

Vote_Sizing_Steve’s picture

After having a hard time with getting Cygwin to work on a prior os, and also having a hard time reverting from the installation (, I'm wondering if there is any alternatives to Cygwin that are more windows-friendly and/or user-friendly.

CPJS’s picture

Thanks. I wanted to help with some issues that I encountered in modules but did not have this great documentation. Thank You. How can I help translate this documentation to other language?

helpmelearn’s picture

Used Git

Download the patch to your working directory. Apply the patch with the following command:
git apply -v [patchname.patch]

Worked like a charm!

doriangray’s picture

Dude, you saved my life, that Cgywin shit simply doesn't work, always display "command not found"
GIT is the way to go!
thanks man!

ah_ma81’s picture

I am having the same problem with Cgywin and it doesn't work.
can you please explain more, Where do i have to add this line
git apply -v [patchname.patch]
and where should i save the patch? in the directory for the module that i want to apply the patch to it?

Tyera’s picture

Thank you for posting this guide. Really helped me on my first patch!

everpat’s picture

The original post and the comment by khosman helped me perform the patch on Windows with no problems. Thanks!

natttan’s picture

When I apply one of commands given in step 4. I am getting this:

can't find file to patch at input line 5
Perhaps you used the wrong -p or --strip option?
The text leading up to this was:
|diff --git a/handlers/ b/handlers/
|index 5a5c4b7..07d1dfd 100644
|--- a/handlers/
|+++ b/handlers/
File to patch:

Does anyone know how to avoid this inconvenient situation?
Thanks in advance!

soegaraedy’s picture

I had similar problem, which was caused by saving a patch file in an incorrect directory. In your case, take a look at these two lines:

--- a/handlers/
+++ b/handlers/

You are supposed to put the patch file under the handlers directory, then this patch file would be next to file. After you move the patch file into that directory, from your cygwin console, get active in that directory using the 'cd' command then execute the patch command (I usually use: patch < your_patch.patch).

Happy Patching !!

S.Wan’s picture

I was trying to apply a patch to the rules_link module, however got this error message unfortunately :

(Stripping trailing CRs from patch; use --binary to disable.)
patching file rules_link.module
patch: **** Failed to set the owning group of file ./rules_link.module.oYaYKxH: Permission denied

I have no clues about this.
Any idea about this?

Many thanks

jdexter’s picture

Hey @natttan .. This is a cross post from another thread - and moving the patch may work - but hoping you find the deets below useful.. They assume you have SSH access to your Drupal Installation on a Linux (in this case Debian) server.

To be honest, I remain GIT curious and may yet have to set it up - but I tend to work on public facing sandboxes and remain uncomfortable with some of the inherent security issues GIT represents .. I'm working towards a 'datacore all in' Drupal Ecomm distribution that does not require direct FTP/SSH server access.

Anyway, you can usually work out how a given patch is trying to apply by looking at the patch for file path its trying to use.

In this case, this is a multi-file patch spanning several core subdirectories from install root .. So first thing is to login and go to your site root (ie var/www/public_html/epicdrupisite/) and download the file from the command line:


If you copied the link - you will likely have to edit 'https' and stick with http as above ..

Saving locally and ftp'ing it in is kinda pointless because you will need ssh to actually apply the patch.

Next trick is help the patch find the right paths for the files - so - you issue a -p option on the command line - in this case:

patch -p1 < drupal7.entity-system.1525176-153.patch

.. there are several -p options, but in this case - you are telling the patch program that this particular patch file is relatively targeting file locations below the patch file and to strip the leading '/' thus:

patching file includes/
patching file modules/simpletest/
patching file modules/simpletest/tests/entity_crud.test
patching file modules/taxonomy/taxonomy.test

.. above is what it should look like after running the command line noted for this patch ..

In the case a module specific patches like this one, you should download a given patch to the module directory itself and then it should be able find any sub-directories relative to the patch from there ..

The primary variations you see are local patches - so no -p .. just

patch < drupal7.some.patch.1525176-153.patch

.. which would patch a file in the same directory as the patch and/or correctly assigned subdir/file.paths .. and ..

patch -p0 < drupal7.some.system.1525176-153.patch

Which would only work for instructions that referenced the patch path from drive root for a file like this:

patching file /var/www/epicdrupsite/sites/all/modules/a_module/includes/
patching file /var/www/epicdrupsite/sites/all/modules/a_module/some.module

.. Have a care when applying patches to pay attention to the date .. A lot of patches are absolutely unique to a given point in time and if your application is updated after the patch was issued, you may need to knit it in manually ..

NEVER use -f (force) option .. Its almost like they left it in there as some sort of embittered gag on the Mac/MicroGoat users out there ..

Cheers - as always - your mileage may differ ..

rionka’s picture

Just a notice: the original cygwin link which leads directly to the exe file, is not valid anymore. Since they started to offer two different installers, there is a link for setup-x86.exe (32-bit installation) or setup-x86_64.exe (64-bit installation) - see I would correct the text myself but unfortunately i'm probably not allowed to edit.

rionka’s picture

Just a notice: the original cygwin link which leads directly to the exe file, is not valid anymore. Since they started to offer two different installers, there is a link for setup-x86.exe (32-bit installation) or setup-x86_64.exe (64-bit installation) - see I would correct the text myself but unfortunately i'm probably not allowed to edit.

tsssystems’s picture

Great how-to. Thanks for the documentation!

kackackacka’s picture

Great step-by-step document for beginners in patching!:-) Thanks a lot!

Sampedro’s picture

Hello people.

Applying a patch with the following settings

Windows + XAMPP + Drupal (Localhost) + CygWin (Linux on Windows)

I had the same problem that many people that I have read here.

Indeed the problem is the difference in file format between Windows and Linux.

Like say in Common Problems :

UNIX vs. Windows end-of-line encoding
Text files originating from UNIX systems use a single linefeed character (LF) to mark the end of a line, whereas Windows systems use a carriage return followed by a linefeed (CRLF).

In this case:

patch {file} {patch} --verbose --binary

no works for me.

To avoid this inconvenience . I downloaded the patch from the cygwin console with the wget command in the directory module.

$ wget

Now and until you edit in Windows , it is entirely Linux file .

I was able to patch the module perfectly.

Use wget to obtain the patches.

Unionhill’s picture

I've been avoiding the "patch thing" for a long time, but the tutorial helped! Thanks. I got it done on my local what? ftp the fixed file over?...or do the same procedure on my server (Go Daddy).
Thanks again!

windm’s picture

First of all: Thank you for this detailed guide!

I tried this way of patching the first time, so had to install cygwin and had to get familiar with that kind of interface - however, it works!

Just a minor detail, I experienced with a Core patch ( The guide above handles a module patch, where you copy the .patch file exactly to the one and only module directory - so it works within that path (that´s obviously, what -p0 does).
To run a patch for a path including all subfolders etc., it is obviously required to use -p1.

This hint will be self explaining for everybody who is familiar with that kind of commands, but may help other newbies (like me), patching a more complex thing than a module.

motrengaw’s picture

Many thanks for this detailed description. I have added a short explanation of the -pN flag for true newbies (like myself) to the Notes section. If there is a similar procedural for newbies (to 'patch') for the linux environment, a line here might be helpful to those landing on this Windows-oriented tutorial. It was easy enough to extrapolate to my Debian situation, but if there is a penguinized version of this that would be a good thing to ling. Again, this was a huuuuge help. A million thanks to the author(s).

hondaman900’s picture

In case it helps someone else also trying to patch Drupal files, I found Netbeans can do this natively (Tools > Apply Diff/Patch) with a nice comparison report afterwards.

adeleke.akinade’s picture

Thanks for this very informative guide. I have applied patches in the past but had to fill in the blanks of a few things so it's great to see a guide that goes into the details of the steps and what they mean.

FYI: it works it Git bash as well.