packaging/installer/methods/macos.md
You can install Netdata in one of the three following ways:
Each of these installation option requires Homebrew for handling dependencies.
:::info
The Netdata Homebrew package is community-created and -maintained.
:::
:::note
Community-maintained packages may receive support from Netdata, but are only a best-effort affair. Learn more about Netdata's platform support policy.
:::
To install Netdata using our automatic kickstart open a new terminal and run:
curl https://get.netdata.cloud/kickstart.sh > /tmp/netdata-kickstart.sh && sh /tmp/netdata-kickstart.sh
The Netdata Agent is installed under /usr/local/netdata. Dependencies are handled via Homebrew.
The kickstart.sh script accepts additional parameters to automatically connect your node to Netdata
Cloud immediately after installation. Find the token and rooms strings by signing in to Netdata
Cloud, then clicking on Connect Nodes on any of the prompts from the UI.
--claim-token: Specify a unique claiming token associated with your Space in Netdata Cloud to be used to connect to the node
after the install.--claim-rooms: Specify a comma-separated list of tokens for each Room this node should appear in.--claim-proxy: Specify a proxy to use when connecting to the Cloud in the form of http://[user:pass@]host:ip for an HTTP(S) proxy.
See connecting through a proxy for details.--claim-url: Specify a URL to use when connecting to the Cloud. Defaults to https://app.netdata.cloud.For example:
curl https://get.netdata.cloud/kickstart.sh > /tmp/netdata-kickstart.sh && sh /tmp/netdata-kickstart.sh --install-prefix /usr/local/ --claim-token TOKEN --claim-rooms ROOM1,ROOM2 --claim-url https://app.netdata.cloud
The Netdata Agent is installed under /usr/local/netdata on your machine. Your machine will also show up as a node in your Netdata Cloud.
If you experience issues while connecting your node, follow the steps in our Troubleshoot documentation.
To connect this Agent to Netdata Cloud, see Connect a Homebrew-installed Agent to Netdata Cloud below.
To install Netdata and all its dependencies, run Homebrew using the following command:
brew install netdata
Homebrew will place your Netdata configuration directory at /usr/local/etc/netdata/.
Use the edit-config script and the files in this directory to configure Netdata. For reference, you can find stock configuration files at /usr/local/Cellar/netdata/{NETDATA_VERSION}/lib/netdata/conf.d/.
To install Netdata and all its dependencies, run Homebrew using the following command:
brew install netdata
Homebrew will place your Netdata configuration directory at /opt/homebrew/etc/netdata/.
Use the edit-config script and the files in this directory to configure Netdata. For reference, you can find stock configuration files at /opt/homebrew/Cellar/netdata/{NETDATA_VERSION}/lib/netdata/conf.d/.
Homebrew installs Netdata but does not start the Agent automatically, so the local dashboard at http://localhost:19999 is not available until you start it yourself. See macOS (Homebrew) for the brew services commands to start, stop, restart, and check the status of the Agent.
The easiest way to connect a Homebrew-installed Netdata Agent to Netdata Cloud is via the local dashboard UI, as described in Method 1: Via UI:
http://localhost:19999 (or the Agent's IP address at port 19999). The Agent must be running first; if you haven't started it yet, see Start the Netdata Agent above.For automated setups or headless machines where the UI is not accessible, you can use one of these alternatives:
/usr/local/netdata by default, or your --install-prefix path) rather than adding flags to an existing Homebrew install. If you want to keep the Homebrew install, use the Configuration file method below. See the kickstart claiming section above or the full kickstart documentation.claim.conf file in your Netdata configuration directory using the configuration file method.Configuration directory paths for claim.conf:
| Architecture | Path |
|---|---|
| Intel | /usr/local/etc/netdata/claim.conf |
| Apple Silicon | /opt/homebrew/etc/netdata/claim.conf |
:::note
On macOS, Homebrew installs run under your user account and the netdata group does not exist. Use your own user and the staff group for file ownership when creating claim.conf manually. For full details on permissions and applying the configuration, see the configuration file method.
:::
:::caution
Do not run the netdata-claim.sh script manually. It is deprecated and will be unsupported in the near future. Instead, use one of the supported claiming methods described above: the Cloud UI, kickstart claiming flags during install/reinstall, or a claim.conf file.
:::
For the full list of claiming options and troubleshooting, see Connect Agent to Cloud.
We don't recommend installing Netdata from source on macOS, as it can be difficult to configure and install dependencies manually.
Open your terminal of choice and install the Xcode development packages:
xcode-select --install
Click Install on the Software Update popup window that appears.
Use the same terminal session to install some of Netdata's prerequisites using Homebrew. If you don't want to use Netdata Cloud, you can omit cmake.
brew install ossp-uuid autoconf automake pkg-config libuv lz4 json-c openssl libtool cmake
To include the OpenTelemetry plugin (otel-plugin), also install a Rust toolchain — either brew install rust or a stable toolchain via rustup. The plugin is built automatically when a toolchain covering the minimum version (rust-version in src/crates/Cargo.toml) is available; without one, the installer prints a warning and builds the agent without the plugin.
Download Netdata from our GitHub repository:
git clone https://github.com/netdata/netdata.git --recursive
cd into the newly-created directory and then start the installer script:
cd netdata/
sudo ./netdata-installer.sh --install-prefix /usr/local
:::info
/usr/local/netdata/./usr/local/lib/netdata/conf.d/.:::
Netdata works on macOS, albeit with some limitations.
otel-plugin) is built by default when a Rust toolchain is available, so a macOS node can also ingest OTLP metrics and logs.