Skip to content

Buildkit

To develop for CiviCRM, you will need the basic requirements (PHP, MySQL, etc) and several specific development tools.

The collection of typical development tools is called civicrm-buildkit. But how do you install it?

Installation Approach Pros / Cons
Full Stack: Install one suite with everything (PHP, MySQL, cv, civix, etc). Pro: You get a comprehensive suite. Everything is configured.
Con: Highly opinionated configurations. You need to find a full stack that comes close to your needs.
Half Stack: Install the basic requirements (PHP, MySQL) on your own. Add buildkit for additional tools (cv, civix, etc). Pro: You can choose how to address basic requirements, but you don't need to manage every tool.
Con: Initial configuration may be tricky. Requires Unix-style environment. Somewhat opinionated.
Custom Stack: Choose and configure every component yourself. Pro: Maximum flexibility. Works on all platforms.
Con: You will need to understand, configure, and maintain all tools. Your toolset may get out-of-sync with other developers' toolset.

Full Stack

For a new or inexperienced contributor, the safest bet is a Full Stack: Virtual Desktop. It provides broad functionality and broad compatibility with very little configuration.

Of course, there are limitations with Virtual Desktop - it's not as fast; it may not use your favorite IDE; and so on. Fortunately, there are other full-stack options (with different trade-offs). Here are a few ways to assemble a full stack:

Full Stack Approach Host Compatibility
Apt-Get: Install PHP, MySQL, etc as local system-packages (/usr). Linux: Native (details)
MacOS: No
Windows: No
Docker: Install PHP, MySQL, etc as headless containers (/var/lib). Linux: Native (x86)
MacOS: Virtual (x86)
Windows: Virtual (x86)
Nix: Install PHP, MySQL, etc as isolated add-on packages (/nix). Linux: Native (x86, arm64)
MacOS: Native (x86, arm64)
Windows: No††
Vagrant: Run a headless virtual machine with PHP, MySQL, etc. Linux: Virtual (x86)
MacOS: Virtual (x86)
Windows: Virtual (x86)
Virtual Desktop: Run a virtual machine with an entire desktop OS and all other requirements. Linux: Virtual (x86)
MacOS: Virtual (x86, arm64)
Windows: Virtual (x86)

: Docker and Vagrant officially support x86 and arm64, but the buildkit configuration is only developed on x86.
††: Nix officially supports WSL2 virtualization, but the buildkit configuration is not tested on WSL2.

Half Stack

If the basic requirements are already provided by your operating system (Debian, Ubuntu, Fedora, RHEL, etc) or add-on stack (MAMP, XAMPP, brew, etc), then consult the generic installation guide for buildkit.

Custom Stack

If you are going to do a custom stack, then there is no specific guide. However, you should review civicrm-buildkit to understand the kinds of tools and configurations that are typically required.