| 1 | # Windows Installation Guide |
| 2 | |
| 3 | [English](./windows-installation.md) | [Chinese](./zh/windows-installation.md) |
| 4 | |
| 5 | --- |
| 6 | |
| 7 | This guide walks you through installing PPT Master on Windows step by step. Follow along and you'll have a working setup in under 10 minutes. |
| 8 | |
| 9 | --- |
| 10 | |
| 11 | ## Step 1 — Install Python (Required) |
| 12 | |
| 13 | Python is the only hard requirement. |
| 14 | |
| 15 | 1. Go to **[python.org/downloads](https://www.python.org/downloads/)** and download the latest **Python 3.10+** installer. |
| 16 | |
| 17 | 2. **⚠️ CRITICAL: Check "Add python.exe to PATH"** during installation — this is the single most common mistake on Windows. Skipping this will break every step that follows. |
| 18 | |
| 19 | 3. After installation, open **PowerShell** (search "PowerShell" in Start menu) and verify: |
| 20 | |
| 21 | ```powershell |
| 22 | python --version |
| 23 | ``` |
| 24 | |
| 25 | You should see `Python 3.12.x` or similar. If you see "Python was not found" or it opens the Microsoft Store, see [Troubleshooting](#python-was-not-found-or-opens-microsoft-store) below. |
| 26 | |
| 27 | > **💡 Tip**: Python installed via Anaconda or Miniconda works too — just make sure `python --version` shows 3.10+. |
| 28 | |
| 29 | --- |
| 30 | |
| 31 | ## Step 2 — Download the Project |
| 32 | |
| 33 | **Option A — Download ZIP** (easiest): |
| 34 | |
| 35 | 1. Go to [github.com/hugohe3/ppt-master](https://github.com/hugohe3/ppt-master), or use the [AtomGit mirror](https://atomgit.com/hugohe3/ppt-master) in mainland China |
| 36 | 2. Click the green **Code** button → **Download ZIP** |
| 37 | 3. Unzip to `C:\Users\YourName\ppt-master` |
| 38 | |
| 39 | **Option B — Git Clone** (requires [Git](https://git-scm.com/downloads)). Run one of these clone commands: |
| 40 | |
| 41 | ```powershell |
| 42 | # GitHub |
| 43 | git clone https://github.com/hugohe3/ppt-master.git |
| 44 | ``` |
| 45 | |
| 46 | ```powershell |
| 47 | # AtomGit mirror |
| 48 | git clone https://atomgit.com/hugohe3/ppt-master.git |
| 49 | ``` |
| 50 | |
| 51 | Then enter the cloned folder: |
| 52 | |
| 53 | ```powershell |
| 54 | cd ppt-master |
| 55 | ``` |
| 56 | |
| 57 | --- |
| 58 | |
| 59 | ## Step 3 — Install Dependencies |
| 60 | |
| 61 | ```powershell |
| 62 | cd C:\Users\YourName\ppt-master # ← adjust to your actual path |
| 63 | pip install -r requirements.txt |
| 64 | ``` |
| 65 | |
| 66 | > If `pip` is not recognized, try `python -m pip install -r requirements.txt`. |
| 67 | |
| 68 | Wait for it to finish. You should see `Successfully installed ...` at the end. |
| 69 | |
| 70 | --- |
| 71 | |
| 72 | ## Step 4 — Verify Your Setup |
| 73 | |
| 74 | ```powershell |
| 75 | python -c "import pptx; import fitz; print('All core dependencies OK')" |
| 76 | ``` |
| 77 | |
| 78 | ✅ Output: `All core dependencies OK` → you're good. |
| 79 | |
| 80 | ❌ Error → see [Troubleshooting](#troubleshooting) below. |
| 81 | |
| 82 | --- |
| 83 | |
| 84 | ## Step 5 — Run a Minimal Example |
| 85 | |
| 86 | Open the `ppt-master` folder in an agent-capable AI tool (Claude Code, Codex, Cursor, a VS Code agent, etc.) and type in the chat: |
| 87 | |
| 88 | ``` |
| 89 | Quickly generate a simple 3-page test PPT with a cover, one content page, and a closing page. Topic: "Hello World". No need to confirm with me. |
| 90 | ``` |
| 91 | |
| 92 | Asking for **quick generation** is what keeps this smoke test short: the AI skips the Strategist analysis and the design-confirmation round trips and goes straight to authoring and export. The default flow confirms the design spec with you first, which is what you want for a real deck but slow when all you are checking is that the environment works. Full guide → [Quick mode](./getting-started.md#quick-mode). |
| 93 | |
| 94 | When it finishes, you should see: |
| 95 | |
| 96 | - A native DrawingML `.pptx` under `exports/`, generated from `svg_output/`, that opens in PowerPoint and remains editable element by element. |
| 97 | |
| 98 | That's the check that matters — if the file is there and opens, **you're done.** Note that quick generation skips `finalize_svg.py`, so there is no `svg_final/` preview directory; the default flow produces one, containing self-contained visual-preview SVGs. They may be inserted manually as SVG pictures, but manual "Convert to Shape" is outside the supported contract. |
| 99 | |
| 100 | --- |
| 101 | |
| 102 | ## Step 6 — Optional Enhancements (most users can skip this) |
| 103 | |
| 104 | With Python and `requirements.txt` installed, you already have everything needed to generate presentations. PPTX export writes native DrawingML shapes, so it does not require CairoSVG, GTK, or a separate SVG rasterization stack. The item below is an **edge-case fallback** — install it only if you hit the specific scenario. |
| 105 | |
| 106 | | Enhancement | Install only if… | How to install | Verify | |
| 107 | |-------------|-----------------|----------------|--------| |
| 108 | | **Pandoc** — legacy document formats | You need to convert `.doc`, `.odt`, `.rtf`, `.tex`, `.rst`, `.org`, or `.typ`. `.docx`/`.html`/`.epub`/`.ipynb` work natively in Python. | Download `.msi` from [pandoc.org](https://pandoc.org/installing.html) | `pandoc --version` | |
| 109 | |
| 110 | --- |
| 111 | |
| 112 | ## Troubleshooting |
| 113 | |
| 114 | ### `python` was not found or opens Microsoft Store |
| 115 | |
| 116 | **Cause**: Python isn't in your system PATH. |
| 117 | |
| 118 | **Fix 1** — Re-run the Python installer → **Modify** → check **"Add Python to environment variables"**. |
| 119 | |
| 120 | **Fix 2** — Manually add to PATH: |
| 121 | 1. Run `where python` in PowerShell first to find the actual path (e.g. `C:\Users\YourName\AppData\Local\Programs\Python\Python312\python.exe`) |
| 122 | 2. Search "Environment Variables" in Start menu |
| 123 | 3. Find `Path` → **Edit** → add the **directory** from step 1 and its `Scripts` subfolder: |
| 124 | ``` |
| 125 | C:\Users\YourName\AppData\Local\Programs\Python\Python312 |
| 126 | C:\Users\YourName\AppData\Local\Programs\Python\Python312\Scripts |
| 127 | ``` |
| 128 | 4. Click OK, then **restart PowerShell** |
| 129 | |
| 130 | **Fix 3** — Try `python3` or `py` instead. |
| 131 | |
| 132 | ### A `python3` command fails (exit 49 / opens Microsoft Store) |
| 133 | |
| 134 | The python.org installer ships `python.exe` but not `python3.exe`. **Just replace `python3` with `python` in the command** (the AI agent usually switches to `python` and continues on its own too). |
| 135 | |
| 136 | ### `pip install` fails with permission errors |
| 137 | |
| 138 | ```powershell |
| 139 | pip install --user -r requirements.txt |
| 140 | ``` |
| 141 | |
| 142 | Or run PowerShell as Administrator. |
| 143 | |
| 144 | ### `pip install` fails due to network issues |
| 145 | |
| 146 | ```powershell |
| 147 | # Tsinghua PyPI mirror |
| 148 | pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple |
| 149 | |
| 150 | # Proxy |
| 151 | pip install -r requirements.txt --proxy http://your-proxy:port |
| 152 | ``` |
| 153 | |
| 154 | ### `ModuleNotFoundError` |
| 155 | |
| 156 | `pip` installed to a different Python. Use `python -m pip install -r requirements.txt` to match. |
| 157 | |
| 158 | ### `import fitz` fails |
| 159 | |
| 160 | 1. Upgrade pip: `python -m pip install --upgrade pip` |
| 161 | 2. Pre-built wheel: `pip install PyMuPDF --only-binary :all:` |
| 162 | 3. Still failing → install [Visual C++ Build Tools](https://visualstudio.microsoft.com/visual-cpp-build-tools/) |
| 163 | |
| 164 | ### PowerShell says "running scripts is disabled" |
| 165 | |
| 166 | ```powershell |
| 167 | Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser |
| 168 | ``` |
| 169 | |
| 170 | --- |
| 171 | |
| 172 | ## Still stuck? |
| 173 | |
| 174 | - 📖 [FAQ](./faq.md) |
| 175 | - 🐛 [GitHub Issues](https://github.com/hugohe3/ppt-master/issues) — include your Python version, Windows version, and full error message |
| 176 | - 💬 [GitHub Discussions](https://github.com/hugohe3/ppt-master/discussions) |
| 177 |