[Doc] Fix macOS installation dependency resolution issue

[shahfasal]

Purpose

Fixes dependency resolution error that prevents macOS users from installing vLLM following the current documentation.

Problem: When running uv pip install -r requirements/cpu.txt on macOS, users encounter a typing-extensions version conflict. This occurs because uv by default only searches the first package index (PyTorch CPU index) and doesn't find compatible versions across multiple indexes (PyTorch CPU + PyPI).

Solution: Add --index-strategy unsafe-best-match flag to the installation command, which instructs uv to search all configured package indexes to find compatible dependency versions.

Test Plan

1. Fresh macOS environment (Apple M3 Max, macOS Darwin 25.0.0)
2. Follow the updated installation instructions in docs/getting_started/installation/cpu/apple.inc.md
3. Verify successful installation without dependency conflicts
4. Run basic vLLM tests to confirm functionality

Test Result

✅ Before fix: Installation failed with typing-extensions dependency resolution error
✅ After fix: Installation completed successfully
✅ Verification: Successfully ran vLLM tests:

# Import test
python -c "import vllm; print(vllm.__version__)"
# Output: 0.1.dev10378+g5c7fe2549

# Model initialization test
python -c "from vllm import LLM; llm = LLM('facebook/opt-125m', max_model_len=512, enforce_eager=True)"
# Output: Successfully initialized

# Unit tests
pytest tests/test_logger.py -v
# Output: 20/20 tests passed

---

Essential Elements of an Effective PR Description Checklist

• The purpose of the PR, such as "Fix some issue (link existing issues this PR will resolve)".
• The test plan, such as providing test command.
• The test results, such as pasting the results comparison before and after, or e2e results
• (Optional) The necessary documentation update, such as updating supported_models.md and examples for a new model.
• (Optional) Release notes update. If your change is user facing, please update the release notes draft in the Google Doc.

[github-actions]

👋 Hi! Thank you for contributing to the vLLM project.

💬 Join our developer Slack at https://slack.vllm.ai to discuss your PR in #pr-reviews, coordinate on features in #feat- channels, or join special interest groups in #sig- channels.

Just a reminder: PRs would not trigger full CI run by default. Instead, it would only run fastcheck CI which starts running only a small and essential subset of CI tests to quickly catch errors.

You ask your reviewers to trigger select CI tests on top of fastcheck CI.

Once the PR is approved and ready to go, your PR reviewer(s) can run CI to test the changes comprehensively before merging.

To run CI, PR reviewers can either: Add ready label to the PR or enable auto-merge.

If you have any questions, please reach out to us on Slack at https://slack.vllm.ai.

🚀

[mergify]

Documentation preview: https://vllm--26721.org.readthedocs.build/en/26721/

[gemini-code-assist]

Code Review

This pull request addresses a dependency resolution error for macOS users by updating the installation instructions. The addition of the --index-strategy unsafe-best-match flag to the uv pip command is a necessary fix. My review includes one suggestion to enhance the documentation by providing more context on the 'unsafe' nature of this flag, which will help users better understand the command they are running. The change is otherwise correct and well-documented.

[gemini-code-assist]

The explanation for --index-strategy unsafe-best-match is good, but the "unsafe" part might worry users. It's worth clarifying what this means in the context of uv and why it's an acceptable solution here. This will build more trust and provide a clearer understanding for users.

Suggested change

The `--index-strategy unsafe-best-match` flag is needed to resolve dependencies across multiple package indexes (PyTorch CPU index and PyPI). Without this flag, you may encounter `typing-extensions` version conflicts.

The `--index-strategy unsafe-best-match` flag is needed to resolve dependencies across multiple package indexes (PyTorch CPU index and PyPI), which is required to prevent `typing-extensions` version conflicts on macOS. The "unsafe" in the flag name indicates that `uv` might pick a package from any configured index to satisfy dependencies, without prioritizing a primary index like PyPI. This is considered safe in this context because we are using the official PyTorch index and PyPI.

[youkaichao]

cc @hmellor

[hmellor]

LGTM, please resolve the conflicts and we can get this merged!

[mergify]

This pull request has merge conflicts that must be resolved before it can be
merged. Please rebase the PR, @shahfasal.

https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/working-with-forks/syncing-a-fork

[shahfasal]

@hmellor i have rebased can you please merge it