Slides

# macOS · uv with Homebrew

## An official alternative to the uv installer

<div class="macos-uv-columns">
<div>
<p>In <strong>Terminal</strong>, check whether Homebrew is available:</p>
<pre><code class="language-bash">brew --version</code></pre>
<p>If it prints a version, install uv, then check it. Run one command at a time:</p>
<pre><code class="language-bash">brew install uv
uv --version</code></pre>
<p><strong>Checkpoint:</strong> <code>uv</code> followed by a version number.</p>
<p>If <code>uv --version</code> already works, continue with the course setup.</p>
</div>
<div>
<figure>
<a href="assets/macos-uv/homebrew-uv.png" target="_blank" rel="noopener"><img src="assets/macos-uv/homebrew-uv.png" alt="Screenshot of the official Homebrew uv formula showing brew install uv." /></a>
<figcaption>Screenshot: <a href="https://formulae.brew.sh/formula/uv">Homebrew’s uv package page</a>.</figcaption>
</figure>
<p><strong>No Homebrew yet?</strong> Follow the installer at <a href="https://brew.sh/">brew.sh</a>, including its printed <strong>Next steps</strong>.</p>
<p>Read the proposed changes before approving installation. On a managed Mac, follow your institution’s installation policy.</p>
</div>
</div>

<p class="macos-uv-source">Sources: <a href="https://docs.astral.sh/uv/getting-started/installation/#homebrew">Astral: install uv</a> · <a href="https://docs.brew.sh/Installation">Homebrew installation and requirements</a>. Checked 22 September 2026.</p>

<aside class="notes">
Homebrew is a package manager. Astral explicitly documents brew install uv as
an installation method. Students need only one uv installation method. If uv
already works, do not install a second copy as a troubleshooting step.
Run brew install uv without sudo. Homebrew's initial installation can request
administrator approval and command-line tools, but ordinary brew install
commands do not need sudo in the default installation.

Homebrew's requirements change. At the source-check date, its supported
configuration is Apple silicon with macOS 15 or newer. Intel Macs are Tier 3
and can require source builds. Consult the linked requirements with the
instructor before adding Homebrew to an older or Intel Mac. The course setup
deck separately covers the Intel Mac cryptography dependency build.

Homebrew avoids the standalone uv installer's shell-profile update step, but
Homebrew's own shell setup may still need attention. If brew is not found after
installing Homebrew, follow its printed Next steps for shellenv.

If the standalone uv installer failed while updating a shell startup file,
the uv binary may already exist. Check it as shown on the next slide before
choosing another installation method.
The screenshot is a cropped capture of the official package webpage, not a
record of an installation on a student's Mac. Image provenance is recorded in
assets/macos-uv/SOURCES.txt.

[Sources]

- https://docs.astral.sh/uv/getting-started/installation/#homebrew
- https://formulae.brew.sh/formula/uv
- https://docs.brew.sh/Installation
</aside>

---

# macOS · shell-file update failed

## “Operation not permitted” at the installer’s final step

An error naming `.bashrc`, `.zshrc`, or `.profile` can happen after uv is copied.
Check the path printed by the installer. For the usual location:

```bash
"$HOME/.local/bin/uv" --version
```

If installation needs a retry, this official option skips shell-profile edits.
Review the installer before running it:

```bash
curl -LsSf https://astral.sh/uv/install.sh | env UV_NO_MODIFY_PATH=1 sh
```

Once the uv binary exists, enable it **for this terminal session**:

```bash
export PATH="$HOME/.local/bin:$PATH"
uv --version
```

Repeat the export in new terminals until your shell setup is repaired.
**Reopening Terminal alone does not repair a failed shell-file edit.**

<p class="macos-uv-source">Sources: <a href="https://docs.astral.sh/uv/reference/installer/#disabling-shell-modifications">Astral: disabling shell modifications</a> · <a href="https://astral.sh/uv/install.sh">installer source and execution order</a>.</p>

<aside class="notes">
This is the reported installation failure: the final step cannot write to a
shell startup file. The current installer copies its binaries before attempting
those edits and can touch multiple shell profiles, even when the user's active
shell is zsh. Inspect the precise error and affected filename.

If the absolute-path version check succeeds, uv is already usable: skip the
retry and run the export. The retry is an alternative to choosing Homebrew.
UV_NO_MODIFY_PATH=1 belongs to the sh process executing the downloaded script,
which is why env appears after the pipe. Setting it only for curl would not
configure the installer. The option skips shell-profile changes; it does not
repair existing file permissions or undo changes from a previous attempt.

This slide assumes the default ~/.local/bin destination. UV_INSTALL_DIR,
XDG_BIN_HOME, or XDG_DATA_HOME can change it: use the path the installer printed.
The export changes only the current shell's environment, not any startup file.
It works in bash and zsh. No administrator rights are needed to set PATH.

Do not rely on ~/.local/bin/env being present after an installation with
UV_NO_MODIFY_PATH=1: the installer can skip creating it along with the profile
updates. Once the cause is resolved, review the relevant shell file with the
instructor and save a copy before adding a persistent PATH setting. Compare
the file before and after the change, then verify uv --version in a new shell.

[Sources]

- https://docs.astral.sh/uv/reference/installer/#disabling-shell-modifications
- https://docs.astral.sh/uv/getting-started/installation/
- https://astral.sh/uv/install.sh
</aside>

---

# macOS · permission for shell-file edits

## Full Disk Access is a conditional troubleshooting step

<div class="macos-uv-columns">
<div>
<p>If <strong>macOS privacy controls</strong> caused the denied write:</p>
<ol>
<li>Open <strong>System Settings > Privacy & Security > Full Disk Access</strong>.</li>
<li>Select <strong>Terminal</strong>, or add it with <strong>+</strong>. Use your editor’s entry for its terminal.</li>
<li>Review and enable access. Quit and reopen the app, then retry the trusted installer.</li>
</ol>
<p>Access includes other apps’ data. Revoke temporary access after troubleshooting and reopen the app.</p>
</div>
<figure>
<a class="macos-uv-settings-crop" href="assets/macos-uv/full-disk-access.png" target="_blank" rel="noopener"><img src="assets/macos-uv/full-disk-access.png" alt="Actual macOS Full Disk Access settings with the Terminal switch off and an add button below the application list." /></a>
<figcaption>Actual macOS settings from the <a href="https://assets.securedata.com/documents/SecureRecovery-for-macOS-manual.pdf#page=5">SecureData manual, p. 5</a>. <strong>Terminal is off</strong> in this example. Other entries belong to the vendor’s setup.</figcaption>
</figure>
</div>

<p class="macos-uv-assistant"><strong>Still blocked?</strong> Share the exact error and filename with the instructor. A coding assistant can explain the redacted error, but check its diagnosis before changing permissions.</p>

<p class="macos-uv-source">Sources: <a href="https://support.apple.com/guide/mac-help/allow-access-to-system-configuration-files-mchlccb25729/mac">Apple: Full Disk Access</a> · <a href="https://developer.apple.com/forums/thread/678819">Apple DTS: file-system permission errors</a>. Next: <a href="setup.html">course setup</a>.</p>

<aside class="notes">
An error while writing ~/.bashrc, ~/.bash_profile, ~/.zshrc, or another startup
file is not evidence of a Downloads or course-folder access problem. The exact
path and the application hosting the installer matter. Files & Folders toggles
for Documents/Downloads do not directly grant access to an ordinary startup
file in the home folder. A symlink into a protected location is a separate case.

Full Disk Access can address macOS mandatory privacy restrictions. The filename
alone does not establish that this is the cause. Apple DTS explains that EPERM
(Operation not permitted) can have several causes and that protected paths vary
between macOS releases. Other possibilities include file flags, a restricted
execution environment, or endpoint security software. Ordinary ownership and
ACL problems need their own diagnosis. Full Disk Access does not repair them.

Ask the instructor or IT to inspect only the named file and relevant metadata,
including its owner, ACL, flags, and any symlink target, rather than running a
blanket chmod/chown, disabling SIP, or reinstalling with sudo. A coding
assistant's diagnosis is a suggestion, not confirmation of the root cause.
No exact error trace or affected Mac was available when authoring this deck.

On a managed Mac, use institutional IT support if policy prevents a change.
If a temporary Full Disk Access grant resolves the profile write, revoke it
when troubleshooting is complete and relaunch the app. The narrower alternative
on the previous slide leaves startup files unchanged and uses a session PATH.

[Sources]

- https://support.apple.com/guide/mac-help/allow-access-to-system-configuration-files-mchlccb25729/mac
- https://support.apple.com/guide/mac-help/change-privacy-security-settings-on-mac-mchl211c911f/mac
- https://developer.apple.com/forums/thread/678819
- https://assets.securedata.com/documents/SecureRecovery-for-macOS-manual.pdf#page=5
</aside>