How to Install Osquery on Windows, Linux, and macOS

Installing osquery takes five minutes per platform. The mistakes that cost teams weeks all happen after the install.

This guide covers how to install osquery on Windows, Linux, and macOS using the official packages, how to run it as a service on each platform, and the three decisions to make before you push it to a thousand machines. Every command below comes from the official osquery documentation or the project's download channels. If you want the concept before the commands, start with what is osquery and come back.

Before you install: three decisions

First, decide what osquery is for in your environment. "Visibility" is not an answer; "continuous software inventory and persistence monitoring" is. The queries you plan to run determine the config you deploy.

Second, decide how configuration will reach the agent. On one machine, a local config file is fine. Past a few dozen hosts you want a fleet manager pushing configs over TLS, because editing JSON on 500 machines is not a job anyone should have.

Third, decide where results go. Osqueryd writes differential results to whatever logger you configure (filesystem, TLS endpoint, syslog, AWS streams). A schedule that logs to a file nobody reads is a space heater. The full deployment picture, including scale and performance, is in our definitive osquery handbook.

One more note on trust. Only install from the official repositories, the signed packages at osquery.io, or a mirror you control. An endpoint agent that runs as root or SYSTEM on every machine you own is exactly the kind of software supply chains get attacked through, and the project signs its releases for that reason. Verify signatures in your packaging pipeline once, automate the check, and never think about it again.

How to install osquery on Linux

Osquery publishes signed packages to official apt and yum repositories, listed at osquery.io/downloads. On Debian and Ubuntu, add the repository key to a dedicated keyring (the modern method, since apt-key is deprecated):

On RHEL, CentOS, Rocky, and other rpm distributions, install the repo package and then osquery:

Verify with the interactive shell, then enable the daemon:

How to install osquery on Windows

The fastest route is Chocolatey. Note that the service is opt in, not automatic:

Without the parameter, Chocolatey installs binaries, example packs, and certificates to C:\Program Files\osquery but starts nothing. You can also install the service later using the daemon's own flag:

For managed fleets, download the signed MSI from the official downloads page and push it through Intune, SCCM, or GPO like any other package. The MSI route gives you version pinning and silent install flags, which matter once updates become a change management event rather than a hobby. The service runs as SYSTEM, so treat the config file's ACLs with the same care as any privileged agent.

How to install osquery on macOS

Download the .pkg from the downloads page and install it, or push it through your MDM:

One macOS specific step trips up almost everyone: the evented process tables built on Apple's EndpointSecurity framework (es_process_events and friends) require the agent to have Full Disk Access under Privacy and Security settings. Without it, osquery runs fine and those tables sit silently empty, per the Fleet guide to evented tables. On a managed fleet, grant the permission through an MDM privacy profile so it applies everywhere at once.

What goes in the config file?

Every platform reads the same JSON structure, and understanding four keys covers most deployments. The options block sets runtime flags like logger type and watchdog behavior. The schedule block maps query names to SQL and an interval in seconds. The packs block imports bundles of related queries from separate files. And decorators attach identifying columns (hostname, UUID) to every result row so logs remain attributable after they leave the host.

A minimal working schedule looks like this:

Two habits pay off immediately. Name queries for what they detect, not what they select, because the name is what you will see in logs at 2 a.m. And set intervals from how often the answer can change, not from enthusiasm. Package inventory once an hour is plenty. Sixty second intervals on slow moving tables multiply cost by 60 and information by zero.

Troubleshooting: the three failures everyone hits

The service will not start. Nine times out of ten the config JSON is malformed. Validate it with osqueryd --config_path /etc/osquery/osquery.conf --config_check, which parses the file and exits with an error message instead of a silent crash loop.

Evented tables return nothing. On macOS this is the Full Disk Access permission described above. On Linux, audit based tables need the corresponding flags enabled (--disable_audit=false) and can conflict with other consumers of the audit subsystem, so check what else on the host claims auditd.

A query is eating CPU. The watchdog will already be restarting the worker; confirm with the osquery_schedule table, which reports per query execution counts and wall time. Find the expensive query, widen its interval or narrow its WHERE clause, and the agent goes quiet again. Diagnosis is a query away, which is fitting.

After the install: make it earn its disk space

Start in the shell on your first host. Three queries tell you the install works and teach the model:

Then move real questions into the daemon's schedule. The shell and the daemon are the same engine with very different jobs, a split we unpack in osqueryi vs osqueryd. The example config ships with sensible defaults, and the watchdog protects hosts from expensive queries out of the box (200MB memory ceiling, 10 percent sustained CPU limit). Leave it enabled. Our query library is a practical menu of scheduled queries worth stealing.

Plan the update cadence now, not later. Osquery releases arrive every couple of months, and some carry security fixes for the agent itself (5.23.1, released June 2026, patched heap overflows in two Windows tables). An agent deployed once and never updated becomes inventory nobody owns. Do the math before choosing manual updates: a 30 minute manual update across 200 unmanaged hosts is 100 hours of work per release, roughly six times a year. That is 600 hours annually, which is why the answer is always your existing package pipeline, never hands on keyboards.

Last, decide who reads the output. Collection without analysis is cost without benefit, the same trap we describe in AI alert triage. At Artemes AI we pair deep endpoint context with an AI engine that reads system state and separates real findings from noise, because the lesson of a decade of endpoint telemetry deployments is that rows are cheap and judgment is not.

How do you install osquery across a whole fleet?

The single host commands above are for learning. Fleet installation is a different job with the same binaries, and it has three moving parts.

Package delivery rides whatever you already have. Ansible, Puppet, or Chef on servers, pointed at the official apt and yum repos. Intune, SCCM, or GPO pushing the MSI on Windows. MDM pushing the pkg plus the Full Disk Access profile on macOS. Do not build a new distribution mechanism for one agent. If you have no configuration management at all, fix that first, because an unmanageable agent fleet is worse than no agent.

Configuration delivery should move off local files as soon as the fleet is real. Osqueryd supports a TLS config plugin: agents enroll against a server with a shared secret, then pull their config and push their results over the same channel. This is what fleet managers implement, and it turns "update the schedule" from a change on every host into a change in one place. Protect the enrollment secret like a credential, because it is one.

Rollout should move in waves. Something like 5 percent of hosts for a week, then 25 percent, then the rest. Watch three numbers per wave: watchdog restarts (expensive queries), log volume per host (schedule tuning), and service uptime (packaging problems). Waves make every failure a small failure. A big bang rollout makes your first bad query a fleet incident.

Frequently asked questions

Does installing osquery require a reboot?

No, on any platform. The agent runs in user space with no kernel extension. On macOS, enabling EndpointSecurity events requires granting Full Disk Access, but not a restart.

Can I install osquery with Ansible, Intune, or MDM?

Yes, and past a few dozen hosts you should. The apt and yum repos work with any configuration management tool, the Windows MSI deploys through Intune, SCCM, or GPO, and the macOS pkg pushes through MDM alongside the privacy profile it needs.

How do I verify the install worked?

Run osqueryi "SELECT version FROM osquery_info;" for the binary, then confirm the service: systemctl status osqueryd on Linux, Get-Service osqueryd on Windows, or sudo launchctl list | grep osquery on macOS.

How do I update osquery once it is installed?

Through the same channel that installed it: apt upgrade or yum update on Linux, Chocolatey or your MSI pipeline on Windows, MDM on macOS. The agent has no self update mechanism, which is a feature. Your package pipeline stays the single source of truth for what runs on your hosts.

Which version should I deploy?

The latest stable release from the official repos unless you have a tested reason not to. Releases include security fixes for the agent itself, so pinning an old version indefinitely is a quiet liability.

The takeaway

Install osquery on one representative host per platform today, straight from the official repos. Spend a week in osqueryi learning what your systems look like as tables. Then, and only then, design the scheduled deployment: config delivery, log destination, update pipeline. Teams that sequence it this way are running useful fleet telemetry in a month. Teams that mass deploy first spend that month drowning in logs they never chose.