This article applies to macOS only.

│ English (en) │ español (es) │ 한국어 (ko) │ русский (ru) │

This article applies to macOS only.

Installing Lazarus on a Mac is not particularly difficult but it is critical that you do the install in the correct order. Skipping steps will almost certainly lead to tears. In brief, here is what you need to do:

Download and install Xcode.
Install the global command line tools for Xcode.
Download and install Free Pascal Compiler and FPC Source (Important do this before you install the Lazarus IDE)
Download and install the Lazarus IDE
Configure LLDB - the Apple supplied (and signed) debugger from within the Lazarus IDE.

  Note: If installing versions of Lazarus prior to 2.0.0 you almost certainly also need gdb, refer to the Legacy information page.

Installation

The detailed instructions assume a recent version of macOS on your Mac, a recent version of Xcode from Apple and a recent version of Lazarus. Further down the page, under Legacy Information, you will see older information that may be relevant if you are using older components. You can assist by replacing out of date info, either deleting it, or, if it may help someone working with a legacy project, moving it to the bottom of the page.

In general, this is about using both the Carbon and Cocoa Widget Set. While Carbon may still be seen as a little more stable, as of release 2.0.0 the 64 bit Cocoa is very close and certainly should be considered. Carbon was intentionally (by Apple) limited to 32 bits and you should be aware that it has been removed completely from macOS 10.15 Catalina which only supports 64 bit Cocoa.

Step 1: Download Xcode

You need the Apple Developer tools, which are a part of the Xcode development environment.

Xcode 11.3 for use on macOS 10.14 Mojave or 10.15 Catalina can be installed from the Mac App store, but you must first move any old Xcode versions from the Applications folder into the trash or rename the Xcode app (eg Xcode.app to Xcode_1014.app).

Older systems:

The developer tools can be installed from the original macOS installation disks or a newer copy downloaded from the Apple Developer Connection (ADC), which requires free registration. Download the Xcode file, it will end up in your Downloads directory as a zip file. Click it. It is unarchived into your Downloads directory. You may be happy with it there but maybe not. Other users will see the path to it but be unable to use it. And it is untidy there. So I moved mine and then told xcode-select where it was moved to (in a terminal) -

mv Downloads/Xcode.app /Developer/.
sudo xcode-select -s /Developer/Xcode.app/Contents/Developer

Step 2: Xcode Command Line Tools

This is shown here as a separate step because it really is a separate step in addition to Step 1. Don't confuse this with the internal Xcode command line tools that the Xcode GUI will tell you are already installed. Lazarus cannot use those Xcode internal command line tools, so do the following (it is quick and easy)-

sudo xcode-select --install
sudo xcodebuild -license accept

Step 3: FPC, FPC Source

Download and install the Free Pascal Compiler (FPC) and source. A compatible FPC (and source) must be installed before you install Lazarus. You have a number of options.

Source Forge

Download the Free Pascal Compiler (FPC) and FPC source from the Lazarus IDE file area. When you arrive at that file area, choose the correct version of your operating system. The vast majority of Mac users should now choose the 64 bit packages in the Lazarus macOS x86-64 directory. Every Mac computer since late 2006 has been 64 bit capable. The fact that Apple has completely dropped all 32 bit support from macOS 10.15 Catalina (released in October 2019) is another reason to choose the 64 bit packages.

These binary install kits are built by the FPC/Lazarus developers and track formal releases. As these install kits are not approved by Apple, you need to hold down the Control key, click the package and choose Open and confirm you want to install from an Unknown Developer.

You might like to apply a simple and quick test of FPC at this stage - Testing FPC installation.

Other FPC Options

fpcupdeluxe

You could also consider using fpcupdeluxe to install FPC and, perhaps Lazarus.

fink

Alternatively, you can use fink, a package manager for macOS to install FPC. Note at the time of writing (Early 2020) fink offers Lazarus 2.0.6. The extra bonus of fink is easy installation as well as clean removal of a huge number of other open source software packages, including Free Pascal crosscompilers for many processors and systems. The choice for Lazarus is between a Carbon or Cocoa look, a gtk2 look, a Qt4-based and a Qt5-based version:

$ fink install lazarus-aqua
// or
$ fink install lazarus-cocoa
// or
$ fink install lazarus-gtk2
// or
$ fink install lazarus-qt4
// or
$ fink install lazarus-qt5

You will be asked, whether to install a number of dependencies, including the Free Pascal Compiler, the Lazarus sources. Simply hit RETURN at the prompt and go for a coffee. It may take quite some time to build all packages, in particular on older Macs.

After installation, Lazarus can be started from the folder /Applications/Fink/. The actual details of FPC and Lazarus are in subdirectories of /sw

With any Lazarus package from fink, these widget sets are supported for your program on macOS:

carbon (Aqua), cocoa, gtk2, qt4 (Aqua), qt5 (Aqua), nogui, win32, win64 and wince.

If you install FPC from fink, you will be fine downloading Lazarus source and compiling as detailed below. However, its possibly not a good idea to mix fink FPC with the Sourceforge binary install of Lazarus.

MacPorts

MacPorts has also a package description of the cocoa-64 bit version of lazarus 2.0.6. Install it with:

$ port install lazarus

Step 4: Install the Lazarus IDE

Download and install the Lazarus IDE from the Lazarus IDE file area. When you arrive at that file area, choose the correct version of your operating system. The vast majority of Mac users should now choose the 64 bit packages in the Lazarus macOS x86-64 directory. Every Mac computer since late 2006 has been 64 bit capable. The fact that Apple has completely dropped all 32 bit support from macOS 10.15 Catalina (released in October 2019) is another reason to choose the 64 bit packages.

Non-release versions of the Lazarus IDE

Fixes 2.0

There are a number of reasons why you may be better off using a non release version of Lazarus, specifically, fixes_2_0. Particularly:

You almost certainly need to target Cocoa, macOS 10.15 Catalina does not support 32 bit Carbon at all.
The Cocoa widget set is steadily improving and the lldb debugger interface has rapidly improved since even v2.0.0.
Fixes_2_0 is a safer and more stable than trunk, but gets the new features much faster than the release version.

Precompiled binaries based on fixes_2_0 are not available from SourceForge but can be obtained from fpcupdeluxe. But here we will discuss downloading source and building. A little slow initially but very reliable and a great test of your compiler install ! You will need svn (its not preinstalled on early macOS, use brew or fink to install).

cd ~
mkdir -p bin/lazarus
cd bin/lazarus
svn checkout https://svn.freepascal.org/svn/lazarus/branches/fixes_2_0 laz_fixes
//-wait some time...
cd laz_fixes
make LCL_PLATFORM=cocoa CPU_TARGET=x86_64 bigide
//-wait some time...
open startlazarus.app --args "--pcp=~/.laz_fixes"

Note I pass a parameter to use a config directory that is based on the name of the actual install directory. It makes some scripting easy.

It is also quite feasible (and perhaps a touch safer) to build a 32 bit Carbon Lazarus IDE and use it to build 64 bit Cocoa applications unless you are running macOS 10.15 Catalina which has removed support for 32 bit Carbon. Replace above make line with "make LCL_PLATFORM=carbon CPU_TARGET=i386 bigide " and setup your project as mentioned in the Carbon and Cocoa section below.

You might like to put a small script in your $HOME/bin directory and even set a path to it (very UNIX!)

#!/bin/bash
LAZDIR="laz_fixes"
cd ~/bin/lazarus/"$LAZDIR"
open ~/bin/lazarus/"$LAZDIR"/lazarus.app --args "--pcp=~/.$LAZDIR"

Trunk

Precompiled binaries based on trunk are not available from SourceForge, so here's how to download the trunk source using svn and build the Lazarus IDE.

cd ~
mkdir -p bin/lazarus
cd bin/lazarus
svn checkout https://svn.freepascal.org/svn/lazarus/trunk laz_trunk
//-wait some time...
cd laz_trunk
make LCL_PLATFORM=cocoa CPU_TARGET=x86_64 bigide
//-wait some time...
open startlazarus.app --args "--pcp=~/.laz_trunk"

To update your existing trunk source:

cd ~/bin/lazarus/laz_trunk
svn update .
//-wait some time...
svn cleanup --remove-unversioned
make distclean all LCL_PLATFORM=cocoa CPU_TARGET=x86_64 bigide
//-wait some time...
open startlazarus.app --args "--pcp=~/.laz_trunk"

Step 5: Configure the Debugger

In versions of Lazarus 1.8.4 and earlier, you needed to use gdb as a debugger, slow to install and hard to sign. Since Lazarus 2.0.0 you can (and should) use LLDB, a debugger provided by Apple, no signing required.

Assuming you have installed what is necessary and started Lazarus, all that remains is configuring the debugger. If you don't do this now, Lazarus will try to use GDB and fail.

First, click Tools->Options->Debugger. Top right of the window now open has a label, "Debugger type and path", you must set both. Select "LLDB debugger (with fpdebug) (Beta)".

If it is not show in the selection list, see below (Installing LazDebuggerFpLLdb".) Note that the image above has a path to LLDB that may well be different to yours, depends on where the XCode tools were installed, in my case /Library . Save those settings and you can now try to compile the almost nothing program that Lazarus has kindly provided for you (click the small green triangle near top left).

Next you see a puzzling question, see image below. Choose a "Debug Format" from one of the offered -

Martin_fr, the person who has given us this interface between Lazarus and LLDB, suggests you use "dwarf3" . Then, you need to enter your password, a macOS cuteness because one application appears to be interfering with another. In this case, that's fine!

When running the debugger from time to time you will be asked for your password to allow debugging. This is for your own safety.

Extra Information on using LLDB

A great deal of information about using LLDB appears in this forum thread https://forum.lazarus.freepascal.org/index.php/topic,42869.0.html Here is a few gems, again, from Martin_fr:

In the unexpected case of problems, it may be worth trying "dwarf with sets" instead of just "dwarf3".

The "debug info" setting only affects the units directly in your project. However units in packages may have debug info too. This can be:

set per package
for many, but not all packages in menu Tools > Configure build Lazarus
project settings > Additions and Overrides

If you change settings for a package, you may as well check into which package you expect to step. Packages you do not step into, do not need debug info.

If you use a type from a package (such as TForm from LCL) it is enough that your unit (in which you declare the variable / must declare and use a variable to include the type) has debug info. Reducing the number of packages with debug info (including those that default to have debug info), can shorten the debuggers start-up time.

Also it may be worth comparing (it has not been tested) the debuggers start up time for the same settings, only changing the checkbox "use external debug info".

This needs to be only set in your project. If set in your project it will affect all packages. (If set in a package it will do nothing / at least should...)

Installing LazDebuggerFpLLdb

If you installed from source and used the bigide parameter to make, then the correct debugger will be installed, as a package, and ready to go. If, however, you installed in another way, it may, or may not be there. From the main IDE screen, click Packages->Install/UninstallPackages. Shown is two lists of packages, the list on the left is installed, the list on the right is available to install. Look for LazDebuggerFpLldb (exactly that, there are some similar named but less suitable packages). If it is on the right hand side, click it, press "Install Selection" and then "Save and rebuild IDE". This will take a little time, the IDE will shutdown and restart and all should be well. Now jump back up the page and continue configuring the debugger.

Compatibility

Not every combination of Lazarus and Free Pascal is compatible with every installation of macOS. Please refer to the following table in order to find the correct version for your development environment:

Lazarus Compatibility Matrix
	Lazarus 1.8.x	Lazarus 2.0.y	Lazarus 2.0.8	Lazarus 2.0.10	Lazarus 2.0.12		Lazarus 2.2.y
	FPC 3.0.4		FPC 3.2.0			FPC 3.2.2
PPC processors
Mac OS X 10.4 (Tiger)^‡	Incompatible	Incompatible	Incompatible	Incompatible	Incompatible	Incompatible	Incompatible
Mac OS X 10.5 (Leopard)^‡	Not tested	Not tested	Incompatible	Incompatible	Incompatible	Incompatible	Incompatible
Intel processors
Mac OS X 10.4 (Tiger)^‡	Incompatible	Incompatible	Incompatible	Incompatible	Incompatible	Incompatible	Incompatible
Mac OS X 10.5 (Leopard)	Not tested	Compatible^	Not tested	Compatible^**^†	Not tested	Not tested	Not tested
Mac OS X 10.6 (Snow Leopard)	Compatible	Compatible^^	Not tested	Not tested	Not tested	Not tested	Not tested
Mac OS X 10.7 (Lion)	Compatible	Not tested	Not tested	Not tested	Not tested	Not tested	Not tested
OS X 10.8 (Mountain Lion)	Compatible^^	Compatible	Compatible**#	Compatible**#	Compatible**#	Compatible#	Compatible
OS X 10.9 (Mavericks)	Compatible^^	Compatible	Compatible**^†	Compatible**^†	Not tested	Not tested	Not tested
OS X 10.10 (Yosemite)	Compatible^^	Compatible	Compatible**^†	Compatible**^†	Not tested	Not tested	Not tested
OS X 10.11 (El Capitan)	Compatible^^	Compatible	Compatible***^†	Compatible^†	Compatible^†	Compatible^†	Comptaible
macOS 10.12 (Sierra)	Compatible^^	Compatible	Compatible***^†	Compatible^†	Compatible^†	Compatible^†	Compatible
macOS 10.13 (High Sierra)	Not tested	Compatible	Compatible***^†	Compatible^†	Compatible^†	Compatible^†	Comptaible
macOS 10.14 (Mojave)	Not tested	Compatible	Compatible***^†	Compatible^†	Compatible^†	Compatible^†	Compatible
macOS 10.15 (Catalina)	Not tested	Compatible	Compatible***^†	Compatible^†	Compatible^†	Compatible^†	Compatible
macOS 11 (Big Sur)	Not tested	Compatible	Compatible***^†	Compatible^†	Compatible^†	Compatible^†	Compatible
macOS 12 (Monterey)	Not tested	Not tested	Not tested	Not tested	Not tested	Not tested	Compatible
macOS 13 (Ventura)	Not tested	Not tested	Not tested	Not tested	Not tested	Not tested	Compatible
macOS 14 (Sonoma)	Not tested	Not tested	Not tested	Not tested	Not tested	Not tested	Compatible
Apple Silicon M series processors
macOS 11 (Big Sur)	Not tested	Not tested	Not tested	Compatible^††	Compatible††	Compatible^†††	Compatible*
macOS 12 (Monterey)	Not tested	Not tested	Not tested	Compatible^††	Compatible^††	Compatible^†††	Compatible*
macOS 13 (Ventura)	Not tested	Not tested	Not tested	Compatible^††	Compatible^††	Compatible^†††	Compatible*
macOS 14 (Sonoma)	Not tested	Not tested	Not tested	Compatible^††	Compatible^††	Compatible^†††	Compatible*

x = 0, 2 or 4; y = 0, 2, 4 or 6

^ Carbon interface compiles - Cocoa does not.

^^ Restrictions apply to debugging with gdb.

* Lazarus 2.2.0 installs universal binaries for FPC 3.2.2, but an Intel Lazarus IDE binary which you can use or recompile the IDE from within itself for a native aarch64 version.

** See Installing Lazarus 2.0.8, 2.0.10 with FPC 3.2.0 for macOS 10.10 and earlier for instructions.

*** See Installing Lazarus 2.0.8 with FPC 3.2.0 for macOS 10.11+ for instructions.

# Cannot run without debugging in the IDE. Can run compiled application outside of the IDE. See Issue #37324. Choose the gdb debugger, change timeout option to false or click through five "timeout" dialogs to run with debugging in the IDE.

^† Cannot "run without debugging" in the IDE. Can run compiled application outside of the IDE. See Lazarus IDE - Unable to "run without debugging" for workaround. See Issue #36780.

^†† You need to compile a native aarch64 version of FPC 3.3.1 (trunk) and Lazarus 2.0.12 from source to support an Apple Silicon M series processor. Refer to these instructions for FPC and these instructions for the Lazarus IDE.

^††† After installing FPC 3.2.2, you need to compile a native aarch64 version of Lazarus from source to support an Apple Silicon M series processor. Refer to these instructions for compiling the Lazarus IDE.

^‡ See the legacy version of this compatibility matrix for recommended installs on very old versions of macOS.

Cocoa 64 bit vs Carbon 32 bit

Lazarus using the Apple 64 bit Cocoa framework will meet the needs of many users. The Apple 32 bit Carbon framework works pretty much as expected but you are advised to try Cocoa first, because Apple has dropped support for 32 bit applications and the Carbon framework from macOS 10.15 Catalina which was released in October 2019.

Alternatives include QT and GTK2+, both requiring additional libraries and GTK2+ on the Mac appears to get little attention these days. QT on the Mac does have some strong supporters on the Lazarus forum.

Cocoa is now undeniably the future on the Mac. It is possible to build an all Cocoa version of Lazarus with release 2.0.0 and later. It is also possible to make a Carbon install of Lazarus (unless you are running macOS 10.15 Catalina) and use that to generate Cocoa 64 bit binaries.

In the Carbon or Cocoa IDE, you need to set the Target to the 64 bit processor and select the Cocoa Widget set:

Open your project with Lazarus and click Project/Project Options
In the "Config and Target" panel set the "Target CPU family" to be "x86_64"
In the "Additions and Overrides" panel click on "Set LCLWidgetType" pulldown and set the value to "Cocoa"
For some reason Lazarus sets the compiler to "/usr/local/bin/ppc386" - which results in 32 bit apps. Make sure under Tools->Options that "Compiler Executable" is set to "/usr/local/bin/fpc" to get 64 bit apps.
Now compile your project - and please feed back any problems you experience.

Downloading the source with svn

The source code is kept in a version control system called subversion or 'svn for short:

macOS 10.5 and higher already contain a command line svn client if you have installed the Xcode command line utilities. Users of earlier versions must install an svn client for macOS. You can also use fink. SVN clients with GUI (graphical user interface) are available from Versiontracker. A quite handy client, which integrates in Finder, is SCPlugin.

Create a directory, where you would like to put the source. You don't need to be root to do this. Any normal user can do this. First create a directory for fpc

(e.g. /Users/username/freepascal)

then open a terminal and do the following:

[]$ svn checkout http://svn.freepascal.org/svn/fpc/trunk fpc

This will create a directory called 'fpc', which can be later used in the IDE.

To download/update the latest changes you can simply do:

[]$ cd /Users/username/freepascal/fpc
[]$ svn update

Building fpc

[]$ svn cleanup --remove-unversioned
[]$ make clean all
[]$ sudo make install

Then download the Lazarus IDE source:

[]$ svn checkout http://svn.freepascal.org/svn/lazarus/trunk lazarus

This will create a directory called 'lazarus'.

To update to the latest changes:

[]$ cd /Users/username/freepascal/lazarus
[]$ svn update

Building Lazarus (Cocoa 64 bit version)

[]$ svn cleanup --remove-unversioned
[]$ make distclean all LCL_PLATFORM=cocoa CPU_TARGET=x86_64 bigide

Building Lazarus (Carbon 32 bit version)

[]$ svn cleanup --remove-unversioned
[]$ make clean bigide

Then start lazarus either via command line (or by double clicking in the finder):

[]$ open lazarus.app

Installing the development version from source

You need the latest released Free Pascal Compiler version installed in order to be able to successfully compile the development (trunk) version.

Legacy Information

Legacy installation information for macOS may be found on this page.

Uninstalling Lazarus and Free Pascal

Installed using fink

The complete uninstall of all fpc and lazarus packages is done with:

fink purge --recursive fpc-config

If you want to preserve changes to the preference file /sw/etc/fpc.cfg, do:

fink remove --recursive fpc-config

For the removal of the Lazarus preference folder and files in your home directory, see below ( Lazarus preference folder).

Installed from packages or source

Normally you uninstall an application on macOS simply by dragging it from the Applications folder to the trash. But because Lazarus and Free Pascal are development tools, they're installed in several folders that you don't normally see in Finder.

You can copy and save the commands below to file uninstallLaz.sh and run it if you need to uninstall Lazarus and Free Pascal. You can usually install newer versions of Lazarus and Free Pascal over older versions, but as with most software it's not a bad idea to clean out everything before you install a newer version. This list of commands should also give you a sense of where the various pieces of Lazarus and Free Pascal are located.

bin=/usr/local/bin
share=/usr/local/share
lib=/usr/local/lib
receipts=/Library/Receipts
private=/private/etc

rm -fv $bin/ppcppc
rm -fv $bin/ppc386
rm -fv $bin/bin2obj
rm -fv $bin/data2inc
rm -fv $bin/delp
rm -fv $bin/fd2pascal
rm -fv $bin/fpc
rm -fv $bin/fpcmake
rm -fv $bin/fpcmkcfg
rm -fv $bin/fpcsubst
rm -fv $bin/fpdoc
rm -fv $bin/fprcp
rm -fv $bin/h2pas
rm -fv $bin/h2paspp
rm -fv $bin/makeskel
rm -fv $bin/mkxmlrpc
rm -fv $bin/plex
rm -fv $bin/postw32
rm -fv $bin/ppdep
rm -fv $bin/ppudump
rm -fv $bin/ppufiles
rm -fv $bin/ppumove
rm -fv $bin/ptop
rm -fv $bin/pyacc
rm -fv $bin/rstconv
rm -fv $bin/unitdiff
rm -r $private/lazarus
rm -r $bin/lazarus
rm -r $share/lazarus
rm -r $share/fpcsrc
rm -r $share/doc/fpc-3.0.3
rm -r $share/examples/fpc-3.0.4

rm -r $lib/fpc

rm -r $receipts/lazarus-*.pkg
rm -r $receipts/fpcsrc-*.pkg
rm -r $receipts/fpc-*.pkg

rm -fv /etc/fpc.cfg

Note that this assumes you have version 3.0.4 of Free Pascal installed. If you have a different version, change the two relevant commands to specify your version.

To run this script, change to the directory where it's stored and enter:

chmod +x uninstallLaz.sh
sudo ./uninstallLaz.sh

Then enter your password when prompted.

Lazarus preference folder .lazarus in the home directory

Note: Lazarus also creates a .lazarus folder in your home directory where it stores environment settings and a list of recently opened projects and files. You can leave this folder alone if you want the new version of Lazarus you're installing to use your old settings. macOS normally doesn't show files or folders whose names start with a dot (.). To see this folder and its contents, enter the following in a terminal window:

cd ~/
ls -al
cd .lazarus
ls

To remove it, execute the following commands:

cd ~/
rm -rv .lazarus

Known issues

FPC 2.4.4 has a bug. You can not compile the IDE with the range check flag -Cr.
On OS X 10.4 you have to manually uninstall any previous version before installing a new dmg. Delete the following files and folders:
- /Developer/lazarus
- /Library/Receipts/lazarus.pkg
- /etc/lazarus
- /usr/local/bin/lazbuild

If installing FPC on macOS Mojave (10.14) with an FPC Installer before v3.0.4a you need to also manually install the SDK headers.
- open /Library/Developer/CommandLineTools/Packages/macOS_SDK_headers_for_macOS_10.14.pkg

Upgrading from Mojave (10.14) to Catalina (10.15)

run "xcode-select --install"
to find the crt1.10.5 change in /etc/fpc.cfg the -Fl behind "#ifdef cpux86_64" from

-Fl/Applications/Xcode.app/Contents/Developer/Toolchain...

to

-Fl/Applications/Xcode.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX.sdk/usr/lib/

Installing Lazarus on macOS

Contents