homebrew-nginx installs a custom NGINX build with extra modules

A tap for a NGINX build with more modules compiled in

homebrew-nginx is a Homebrew tap, which means it is not a program but a source of formulae. The formula it publishes is nginx-full, and the tap exists for one reason: to provide a custom build of NGINX with more module options than the standard build gives you.

That distinction matters for the modules question. A Homebrew formula compiles NGINX with a fixed set of module options, and a module that is not in that set is not something you can switch on later. If you need the upload module, or a specific third party module, you need a formula built with it, and that is what this tap provides.

The repository is small by design. The top level holds a Formula directory, a README, a LICENSE, a .github directory with the contributing guide, and a .travis.yml file. There is no source tree for NGINX itself, no build script and no documentation site in the repository. The tap publishes formulae, and the work of building NGINX happens on the machine that installs them.

The homepage points at a documentation site that lists the available modules, and the readme refers to it when it explains how to install with additional modules.

Tapping the repository and installing nginx-full

Two commands do the work. The first taps the repository so that Homebrew knows where to look, the second installs the formula with the module options you want.

    brew tap denji/nginx
    brew install nginx-full --with-upload-module

The option syntax is worth pausing on. The readme presents the extra modules as flags passed at install time, and it points at a modules section of the documentation site for the list of what is available. The readme does not say how these options behave with current Homebrew versions, and it does not describe what happens if you install without any option at all.

If you are unsure what you are getting, the readme gives you two commands to look before you commit to an install.

    brew options nginx-full
    brew info nginx-full

The first lists the available configuration options for the formula, and the second shows the general information about the package, which in Homebrew means the version, the dependencies and the options together. Running both before installing is the sensible order, since the difference between the build you want and the build you get is expressed entirely in those options.

For the documentation of the tooling itself rather than of this tap, the readme points at brew help, man brew and Homebrew's own documentation repository.

Two NGINX installs can coexist, but only one can be linked

This is the part of the readme that answers the question every new user has, which is what happens if NGINX is already installed.

The answer is that you are free to install this version alongside a current install of NGINX from Homebrew/homebrew. Both versions can exist on the machine at the same time. What they cannot do is be linked at the same time, because linking is what puts the binaries on your PATH, and two NGINX binaries on one PATH is a coin toss every time you type nginx.

Switching between them uses Homebrew's built in linking system.

    brew unlink nginx
    brew link nginx-full

Unlinking the upstream formula and linking nginx-full switches you over, and the reverse sequence switches back. Nothing is uninstalled in either direction, so the cost of switching is two commands rather than a reinstall.

That design has a consequence worth planning for. If a script, a launch agent or a Docker-adjacent tool on your machine expects the upstream nginx binary at a particular path, linking the tap version can change what that path resolves to. The readme does not cover that case, and the safe approach is to check what your PATH looks like after a link change rather than assume the two setups are interchangeable.

Adding a formula: fork, branch, test locally, pull request

The readme documents how to submit a new formula to the tap, which is a useful window into how the project is run.

The flow is the standard Homebrew contribution shape. Fork the repository on GitHub and clone it to your Mac. Read the existing formulae to see the conventions. Create a branch in your local clone with git checkout --branch my_new_formula, then write or edit your formula, which is a Ruby file, following Homebrew's own documentation for the format.

The testing step is the one that matters and it is explicit: test it locally with brew install ./my-new-formula.rb, where the ./ prefix targets the local file rather than anything in a tap. Then push the branch to your fork with git push --set-upstream origin my_new_formula, and open a pull request from that branch on GitHub.

If something needs changing, the instruction is to add a commit and git push again, which updates the same pull request rather than opening a new one.

The project keeps a contributing guide at .github/CONTRIBUTING.md for the conventions that are not repeated in the readme, and the presence of a .travis.yml file at the root shows that continuous integration is part of the workflow for the formulae themselves.

A custom licence is the first thing to read

The licence on this repository is the one detail that deserves attention before you install anything, and it is easy to miss precisely because it is not a standard one. GitHub cannot classify it, and the readme points at the LICENSE file rather than naming a licence you recognise.

That matters for a tap because installing a formula runs its build on your machine. Whatever the LICENSE grants, and whatever it restricts, applies to the software you are about to compile and run, so the text is worth reading before the install rather than after. This is not a claim about what the terms are, since the repository does not summarise them, only a note that they are custom and that the file is the source.

The repository is not archived, and the last push was on 2026-08-04. There are no GitHub releases, so there is no tag history to read and no changelog to check, which means the visible record of what changed is the commit history and the pull requests.

That is a reasonable shape for a personal tap, and it is also a different risk profile from the upstream Homebrew project, where formulae are maintained in the open by many people and reviewed before they land. A single maintainer with a custom licence is a different dependency from the one you get from Homebrew/core.

When the upstream formula is the better answer

The alternative here is not another tap, it is the formula you already have. Homebrew's own nginx formula builds NGINX with the module set the Homebrew project decided on, and for most workloads that set is enough. Installing a third party build to get a module you do not use adds a licence to read, a second NGINX on the machine and a linking dance to manage, in exchange for nothing.

So the decision hinges on one question: do you need a module that the upstream build does not include. If the answer is no, the upstream formula is simpler, and simplicity here is worth more than the option to compile something extra later. If the answer is yes, this tap is the direct route, and the upload module in the readme example is the kind of thing people reach for it.

There is a second question worth asking, which is how many NGINX installations you actually want. The tap supports both versions on one machine and gives you a switch between them, which is convenient for trying a module out and reverting. It is less convenient than a single NGINX if your scripts assume one.

And a third, which is whether the module list will still cover you in a year. The tap's own documentation site is where the module list lives, and the formula versions in it move with NGINX releases, so a decision made on today's list is a decision you may revisit at the next NGINX upgrade.

Editorial conclusion

homebrew-nginx suits macOS developers who need an NGINX module that the upstream Homebrew formula does not build, and who are comfortable with a tap maintained by one person rather than by the Homebrew project. It is the wrong tool if the upstream nginx formula already covers your needs, if you want more than one NGINX on your PATH at the same time, or if you cannot accept a custom licence whose text you have not read. Check first that the module you need is listed among the tap's configuration options, that your machine can link only one NGINX at a time, and that the LICENSE file grants you the rights you need before you install anything from this tap.

Frequently asked questions

Official sources

1. denji/homebrew-nginx on GitHub
2. Issues
3. Project website
4. README