Daily Intune News
Aboutmerill.net
Microsoft Intune
Endpoint analytics

Use Shell Scripts on macOS Devices in Microsoft Intune - Microsoft Intune | Microsoft Learn

9 November 2026Doc update+63 / −58 lines

In brief

The article updates its description, date, prerequisites, script behavior guidance, and setup wording. It now emphasizes run frequency, retries, and user context, while revising or removing some scope-tag, assignment, and retry-setting instructions.

What Intune admins need to know

Review the revised guidance when creating or troubleshooting macOS shell scripts, particularly the direct Internet requirement and execution settings. No administrator action is specified.

This summary was assembled from the tracked documentation change. Verify important details in the full Microsoft Learn article.

Documentation change

View full page diffView on Microsoft Learn

The comparison below shows only the changed extract. Use the full-page view for complete context.

  • M365-identity-device-management
  • macOS ms.subservice: apps description: Create, assign, monitor, and troubleshootDeploy shell scripts forto macOS devices inwith Microsoft Intune. Configure run frequency, retries, and user context, then monitor results. ms.date: 2024-08-08T00:2026-11-02T00:00:00.0000000Z ms.topic: how-to ms.reviewer: arnab locale: en-us

Use Shell Scripts on macOS Devices in Microsoft Intune - Microsoft Intune | Microsoft Learn

Use shell scripts to extend device management capabilities in Intune, beyond what is supported by the macOS operating system.system supports.

Note

Rosetta 2 is required to run x64 (Intel) version of apps on Apple Silicon Macs. To install Rosetta 2 on Apple Silicon Macs automatically, you can deploy a shell script in Intune. To view a sample script, see Rosetta 2 Installation Script.

Prerequisites

Ensure that the following prerequisites are met when composing shell scripts and assigning them to macOS devices.

  • Devices are runningrun macOS 12.0 or later.
  • Devices are managed by Intune.Intune manages the devices.
  • Devices are connectedconnect directly to the Internet. ConnectionIntune doesn't support connection through a proxy is not supported.proxy.
  • Shell scripts begin with #! and must beare in a valid location such as #!/bin/sh or #!/usr/bin/env zsh.
  • Command-line interpreters for the applicable shells are installed.

Important considerations before using shell scripts

  • Shell scripts require that the Microsoft Intune management agent is successfully installed on the macOS device. For more information, see Microsoft Intune management agent for macOS.
  • Shell scripts run in parallel on devices as separate processes.
  • Shell scripts that are run as the signed-in user will run for all currently signed-in user accounts on the device at the time of the run.
  • An end user is required tomust sign in to the device to execute scripts running as a signed-in user.
  • Root user privileges are required if the script requires makingneeds to make changes that a standard user account cannot.can't make.
  • Shell scripts will attempt to run more frequently than the chosen script frequency for certain conditions, such as if the disk is full, if the storage location is tampered with, if the local cache is deleted, or if the Mac device restarts.
  • Shell scripts that are runningrun for longer than 60 minutes are stopped and reported as "failed".

Create and assign a shell script policy

  1. In Basics, enter the following properties, and select Next:

    • Name: Enter a name for the shell script.
    • Description: Enter a description for the shell script. This setting is optional, but recommended.We recommend this optional setting.

  2. In Script settings, enter the following properties, and select Next:

    • Upload script: Browse to the shell script. The script file must be less than 1 MB in size.
    • Run script as signed-in user: Select Yes to run the script with the user's credentials on the device. Choose No (default) to run the script as the root user.
    • Hide script notifications on devices: By default, script notifications are shown for each script that is run.runs. End users see a IT is configuring your computer notification from Intune on macOS devices.
    • Script frequency: Select how often the script is to be run.runs. Choose Not configured (default) to run a script only once. Scripts with a frequency set will also run after a device restart.
    • Max number of times to retry if script fails: Select how many times the script should be run if it returns a non-zero exit code (zero meaningmeans success). Choose Not configured (default) to not retry when a script fails.

  3. In Scope tags, optionally add scope tags for the script, and select Next. You can useUse scope tags to determine who can see scripts in Intune. For full details about scope tags,more information, see Use role-based access control and scope tags for distributed IT.

  4. Select Assignments > Select groups to include. An existing list of Microsoft Entra groups is shown. Select one or more user or device groups that are to receive the script. Choose Select. The groups you choose are shown in the list, and willlist. They receive your script policy.

    Note

    • Shell scripts assigned to user groups appliesapply to any user loggingsigning in to the Mac.

    • Updating assignments for shell scripts also updates assignments for Microsoft Intune MDM Agent for macOS.

  5. In Review + add, a summary is shown of the settings you configured. Select Add to save the script. When you select Add, the script policy is deployed to the groups you chose.

The script you created now appears in the list of scripts. If needed, you can view the contents of macOS shell scripts after you upload them to Intune.

Important

IrrespectiveRegardless of the selected Script frequency, the script run status is reported only when the status changes from the last report. For example, if a script reports SucessSuccess in one run and Failure in the next, Intune updates both the status and last updated timestamp with the current run information. If the script status does notdoesn't change across syncs, Intune updates the last updated timestamp every 7seven days from the initial run.

OnceWhen a script runs, it returns one of the following statuses:

  • A script run status of Failed indicates that the script returned a non-zero exit code or the script is malformed.
  • A script run status of Success indicatedindicates that the script returned zero as the exit code.

Troubleshoot macOS shell script policies using log collection

Requirements for log collection

The following items are required toTo collect logs on a macOS device:device, you need to provide the following information:

  • You must specify theThe full absolute log file path.
  • File paths must be separated usingby only a semicolon (;).
  • TheA maximum log collection size to upload isof 60 MB (compressed) or 25 files, whichever occurscomes first.
  • FileAllowed file types that are allowed for log collection include the following extensions: .log, .zip, .gz, .tar, .txt, .xml, .crash, .rtf.

Collect device logs

  1. Sign in to the Microsoft Intune admin center.

  2. NavigateGo to Devices > Manage devices > Scripts and remediations > Platform scripts and select a macOS shell script.

  3. In Device status or User status report, select a device.

  4. Select Collect logs, provide and enter folder paths of log files separated by only by a semicolon (;) without spaces or newlines in between paths.

    For example, write multiple paths should be written as /Path/to/logfile1.zip;/Path/to/logfile2.log.

    Important

    Multiple log file paths separated using comma, period, newlineUsing commas, periods, newlines, or quotation marks with or without spaces will result into separate multiple log file paths causes a log collection error. Spaces are also not allowedDon't use spaces as separators between paths.

  5. Select OK. Logs are collected the next time theThe Intune management agent on the device collects logs the next time it checks in with Intune. This check-in usually occurshappens every 8 hours.

    Note

    • Collected logs are encrypted on the device, transmittedThe device encrypts collected logs, transmits them, and storedstores them in Microsoft Azure storage for 30 days. Stored logs are decrypted on demand and downloaded usingThe Microsoft Intune admin center.center decrypts and downloads stored logs on demand.
    • In addition to the admin-specified logs, the Intune management agent logs are also collectedcollects logs from these folders: /Library/Logs/Microsoft/Intune and ~/Library/Logs/Microsoft/Intune. The agent log file-file names are IntuneMDMDaemon date--time.log and IntuneMDMAgent date--time.log.
    • If any admin-specified file is missing or has the wrong file-file extension, you will find these file-file names listed in LogCollectionInfo.txt.

Log collection errors

Log collection may notmight be successfulunsuccessful due to any of the following reasons provided in the table below.reasons. To resolve these errors, follow the remediation steps.

Error code (hex) Error code (dec) Error message Remediation steps
0X87D300D1 2016214834 Log file size cannotcan't exceed 60 MB. Ensure that compressed logs are less than 60 MB in size.
0X87D300D1 2016214831 The provided log file path must exist. The system user folder is an invalid location for log files. Ensure that the provided file path is valid and accessible.
0X87D300D2 2016214830 Log collection file upload failed due to expiration of upload URL. Retry the Collect logs action.
0X87D300D3, 0X87D300D5, 0X87D300D7 2016214829, 2016214827, 2016214825 Log collection file upload failed due to encryption failure. Retry log upload. Retry the Collect logs action.
2016214828 The number of log files exceeded the allowed limit of 25 files. OnlyYou can collect only up to 25 log files can be collected at a time.
0X87D300D6 2016214826 Log collection file upload failed due to zip error. Retry log upload. Retry the Collect logs action.
2016214740 The logs couldn't be encrypted as compressed logs were notweren't found. Retry the Collect logs action.
2016214739 The logs were collected but couldn't be stored. Retry the Collect logs action.

Custom attributes for macOS

You can create custom attribute profiles whichthat enable you to collect custom properties from managed macOS devicedevices by using shell scripts.

Create and assign a custom attribute for macOS devices

Additional details:

- The shell script must echo the attribute to be reportedreport, and the data type of the output must match the data type of the attribute in the custom attribute profile.
- The result returned by the shell script must be 20KB20 KB or less.

Note

When using `Date` type attributes, ensure that the shell script returns dates in ISO-8601 format. See the examples below.following examples.

**To print an ISO-8601-compliant date with time-zone:**

var=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
echo $var # Prints an ISO-8601 compliant date in UTC time
```

  1. In Assignments, clickselect Select groups to include. When you choose Select groups to include, an existing list of Microsoft Entra groups is shown. Select one or more user or device groups that are to receive the script. Choose Select. The groups you choose are shown in the list, and willlist. They receive your script policy.

    Alternatively, you can choose to select All users, All devices, or All users and all devices by selecting one of these options in the dropdown box next to Assign to.

    Note

    • Scripts assigned to user groups appliesapply to any user loggingsigning in to the Mac.

  2. In Review + add, a summary is shown of the settings you configured. Select Add to save the script. When you select Add, the script policy is deployed to the groups you chose.

The script you created now appears in the list of custom attributes. If needed, you can viewView the contents of custom attributes after you upload them to Intune.

Monitor a custom attribute policy

Important

Shell scripts provided in custom attribute profiles are run every 8 hours on managed Macs and reported.report their status.

OnceWhen a custom attribute profile runs, it returns one of the following statuses:

  • A status of Failed indicates that the script returned a non-zero exit code or the script is malformed. The error is reported in the Result column.
  • AsA status of Success indicates that the script returned zero as the exit code. The output echoed by the script is reported in the Result column.

Frequently asked questions

Why are assigned shell scripts not running on the device?

ThereSeveral reasons could be several reasons:cause this problem:

  • The agent might need to check in to receive new or updated scripts. This check-in process occurs every 8 hours and is different from the MDM check-in. Make sureEnsure that the device is awake and connected to a network for a successful agent check-in and wait for the agent to check in. You can also request the end user to open Company Portal on the Mac, select the devicedevice, and clickselect Check settings.
  • The agent maymight not be installed. Check that the agent is installed at /Library/Intune/Microsoft Intune Agent.app on the macOS device.
  • The agent maymight not be in a healthy state. The agent will attemptattempts to recover for 24 hours, remove itselfitself, and reinstall if shell scripts are still assigned.

How frequently is script run status reported?

When are shell scripts run again?

AWhen a script is run again only whenreturns a non-zero exit code, Intune retries it according to the Max number of times to retry if script fails setting. If that setting is Not configured, Intune doesn't retry the failed run and the script fails on run. If the Max number of times to retry if script fails is not configured and a script fails on run, it will not be run again and runreports its status will be reported as failed. Scripts with a configured frequency can also run again on schedule or after a device restart.

What Intune role permissions are required for shell scripts?

Your assigned-intuneassigned Intune role requiresneeds Device configurations permissions to delete, assign, create, update, or read shell scripts.

Known issues

  • No script run status: InIf the unlikely event thatdevice receives a script is received on the device and the devicebut goes offline before it reports the run status is reported,status, the device will notdoesn't report the run status for the script in the admin center.

Additional information

\ No newline at end of file When you deploy shell scripts or custom attributes for macOS devices from Microsoft Intune, it deploysyou deploy the new universal version of the Intune management agent app that runs natively on Apple Silicon Mac machines. The same deployment will installinstalls the x64 version of the app on Intel Mac machines.

You need Rosetta 2 is required to run the x64 (Intel) version of apps on Apple Silicon Macs. To automatically install Rosetta 2 on Apple Silicon Macs automatically,Macs, you can deploy a shell script in Intune. To view a sample script, see Rosetta 2 Installation Script. \ No newline at end of file \ No newline at end of file

Daily Intune.Admin.News

Get daily email updates

Get a concise summary of the latest Microsoft Intune updates delivered straight to your inbox.

Loading the secure signup form…