Skip to content

CPython Installation Failures

Jump to bottom
Graham Wheeler edited this page Aug 12, 2025 · 1 revision

FAQ: “CPython failed to install” when adding the Python (PTVS) workload in Visual Studio

TL;DR
When you add the Python workload, Visual Studio can (optionally) install a specific CPython build (e.g., CPython3.Exe.x64 3.7.8). If that installer fails, you’ll see lines like:

PackageId:CPython3.Exe.x64; PackageAction:Install; PackageVersion:3.x.y; ReturnCode:1638;

These failures come from the CPython installer (python.org), not from PTVS itself. You don’t need that exact Python to use PTVS—you can install any supported Python yourself and point Visual Studio at it, or uncheck the CPython component entirely.

What’s happening?

  • The Python workload includes an optional “Python X (64-bit)” component that invokes the official CPython Windows installer (an .exe that chains MSIs).

  • If the CPython installer returns a non-zero exit code, the Visual Studio Installer surfaces it as ReturnCode:<number> in the log.

  • Common reasons include: a different Python is already installed, another install is in progress, permission/policy blocks, a corrupted package, or a reboot is pending.

Quick ways to get unblocked

  1. Skip the bundled CPython and use your own Python.

    • Visual Studio Installer → Modify → uncheck the CPython component under the Python workload (or Individual components).

    • Install Python yourself (python.org, Anaconda/Miniconda, etc.).

    • In Visual Studio: View → Other Windows → Python Environments → Add Environment → Existing and browse to your python.exe.

  2. If you want the bundled CPython, clear the blockers and retry:

    • Reboot (clears “another installation in progress” and pending-reboot issues).

    • Close other installers/updates (including Windows Update).

    • Ensure you have admin rights if installing for all users (to Program Files).

    • Temporarily disable security software that blocks MSI installs (if permitted by policy).

    • Make sure the package cache/download isn’t corrupted; choose Repair in the Visual Studio Installer if necessary.

Common return codes, what they mean, and how to fix

ReturnCode What it usually means (plain English) Typical reasons What to try
0 Success — —
3010 Success, reboot required Installer needs a restart to finish Reboot, then retry the VS install step if needed
1602 User canceled You (or policy) stopped the install Re-run and let it complete
1603 Fatal error during installation Locked files, AV block, insufficient rights, path issues, pending reboot Reboot; run as admin; ensure free disk space; disable AV temporarily; run the CPython installer interactively to see its UI/error
1618 Another installation is already in progress Windows Installer is busy (Windows Update, Office, another VS instance) Wait for the other install to finish; reboot if unsure
1619 Could not open installation package Corrupt or missing package; network/layout cache issue Repair the VS Installer; ensure connectivity; refresh offline layout if you’re using one
1620 Invalid installation package Damaged download or wrong architecture Repair/reacquire packages; verify you’re on a supported OS/arch
1638 / 0x80070666 Another version of this product is already installed You already have the same major/minor CPython with the same product code (e.g., Python 3.7 x64) Either uninstall the existing Python of that line, upgrade/downgrade manually to the requested version, or skip the bundled CPython and point PTVS to your existing Python
1639 Invalid command line Unexpected install flags Rare in VS scenario—retry; if it persists, skip bundled CPython and install manually
1925 Insufficient privileges Installing “for all users” without admin Run elevated or choose per-user install when running CPython interactively
0x80070005 Access denied Permissions, AppLocker/SRP, Controlled Folder Access Install as admin; adjust policy or install per-user; choose a writable location
2502 / 2503 Internal MSI errors writing temp/cache TEMP permissions, AV interference Fix %TEMP% permissions; clear TEMP; disable AV temporarily; reboot

Note: The CPython bootstrapper may map MSI errors to HRESULTs (e.g., 0x80070643 ≈ MSI 1603). Treat them per the table.

Typical scenarios & mitigations

  • “I already have Python installed.”
    Great—uncheck the CPython component in the VS Installer and keep your existing install. Add it in Python Environments in VS.

  • “ReturnCode 1638 / 0x80070666.”
    You already have that CPython product line (same major/minor and architecture). Either uninstall the existing one, install the exact version VS requested, or skip the bundled CPython and use your own.

  • “ReturnCode 1618.”
    Another installer is running. Close other installers, wait for Windows Update to finish, or reboot, then retry.

  • “ReturnCode 1603.”
    Generic fatal error. Reboot first. Then run the standalone CPython installer interactively (download the same version/arch) so you can see any prompts/errors (UAC, path, feature selection). If it succeeds, rerun VS with the CPython component unchecked (since Python is now present).

  • Corporate/locked-down machines.
    Group Policy/AppLocker or EDR may block MSI installs to Program Files. Install per-user (no admin) by running the CPython installer yourself and choosing “Just for me,” or work with IT to allow the package. Otherwise, skip the bundled CPython.

  • Offline layout or corrupted cache.
    If you install VS from an offline layout or a stale cache, CPython packages may be missing or corrupt (1619/1620). Refresh the layout or choose Repair in Visual Studio Installer.

Do I need the exact CPython version Visual Studio tries to install?

No. PTVS works with a range of Python 3.x versions. You can install a newer Python (e.g., 3.11/3.12), point VS to it, and skip the older bundled one.

How do I point Visual Studio at an existing Python?

  1. View → Other Windows → Python Environments

  2. Add Environment → Existing

  3. Browse to your python.exe (e.g., C:\Users\<you>\AppData\Local\Programs\Python\Python312\python.exe or your conda env).

  4. Let VS discover packages and interpreters.

When should I file an issue against PTVS?

  • If Visual Studio misreports the error (e.g., no return code, or the UI indicates success but Python isn’t installed), or if the Python Environments window fails to detect a valid Python you’ve installed—file it against PTVS with your VS setup logs.

When should I file an issue against CPython (python.org installer)?

  • If running the standalone CPython installer (outside VS) fails in the same way. Include the installer version, architecture, Windows version, and the installer log (run interactively or with logging enabled), plus any error dialogs.

Collecting useful logs

  • In Visual Studio Installer: after a failure, choose More → View Log for the operation and look for the CPython3.Exe.x64 entry and its ReturnCode.

  • When testing outside VS, run the CPython installer interactively so you can capture any prompts or error text. (If you use MSI directly, you can enable verbose logging with msiexec /i <package.msi> /L*V c:\temp\py.log.)

Best practices to avoid these failures

  • Install Python before adding the VS workload (so VS doesn’t try to add its own).

  • Prefer per-user installs if you don’t have admin rights.

  • Keep only the Python versions you actually need (multiple side-by-side installs can trigger 1638-style conflicts within the same major/minor line).

  • Reboot before installing large workloads to clear pending operations.

  • Avoid running multiple installers at once.

If you’re stuck after trying the above, the fastest path is usually:

  1. Reboot → 2) Install your preferred Python manually → 3) In VS Installer, uncheck the CPython component → 4) Point VS to your Python.

Clone this wiki locally