Skip to main content

How to Resolve Python Pip Error "OSError: [WinError 2] The system cannot find the file specified"

When installing or upgrading Python packages on Windows using pip, you might encounter OSError: [WinError 2] The system cannot find the file specified. This specific Windows error usually indicates that pip was trying to access or modify a file or directory during the installation process, but the specified path could not be found. Common causes include exceeding Windows' default maximum path length limit or issues related to file locking or a corrupted package state.

This guide explains the primary causes of this WinError 2 during pip operations and provides effective solutions, focusing on enabling long path support.

Understanding the Error: File Not Found During Pip Operations​

The OSError: [WinError 2] is the standard Windows error code for "File Not Found". When pip raises this during installation or upgrade, it means an operation like accessing, reading, writing, renaming, or deleting a specific file or directory failed because Windows reported that the target path doesn't exist.

Looking at the full error message often provides clues. If the path mentioned is very long (especially involving AppData, deeply nested site-packages, or long package names/versions), the MAX_PATH limit is a likely culprit. Sometimes, pip tries to rename a file to <filename>.deleteme before replacing it; if the original file is unexpectedly missing or locked, this might also manifest as WinError 2.

Cause 1: Windows MAX_PATH Limit Exceeded (Common)​

Historically, Windows had a default maximum path length limitation (often referred to as MAX_PATH) of 260 characters for many file operations. Python installations, especially user-specific installations (--user) or those within virtual environments located deep within user profiles (C:\Users\YourUsername\AppData\...), can easily create paths for package files (site-packages\<package_name>-<version>.dist-info\METADATA, etc.) that exceed this limit. When pip tries to access these long paths, the operation fails with WinError 2.

Modern versions of Windows (Windows 10, version 1607 and later) allow you to disable the legacy MAX_PATH limit. Enabling this feature is often the most effective solution for WinError 2 caused by long paths during pip install.

Using Registry Editor (regedit)​

  1. Press Win + R, type regedit, and press Enter (or click OK). Accept the User Account Control prompt if it appears.
  2. Navigate to the following key in the left pane: HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\FileSystem
  3. Find or Create: Look for a value named LongPathsEnabled in the right pane.
    • If it exists, double-click it.
    • If it doesn't exist, right-click in the right pane -> New -> DWORD (32-bit) Value -> Name it LongPathsEnabled. Then double-click the new value.
  4. Set Value: Change the "Value data" field to 1. Ensure the "Base" is set to Hexadecimal. Click OK.
  5. Restart: Close the Registry Editor and restart your computer for the change to take full effect.
  6. Retry the pip install command after restarting.

Using PowerShell (Administrator)​

  1. Search for "PowerShell".
  2. Right-click "Windows PowerShell".
  3. Select "Run as administrator". Accept the UAC prompt.
  4. Paste and run the following command: 
    Set-ItemProperty -Path "HKLM:\SYSTEM\CurrentControlSet\Control\FileSystem" -Name "LongPathsEnabled" -Value 1 -Force
  5. Restart: Close PowerShell and restart your computer.
  6. Retry the pip install command.

Cause 2: File Locking or Corrupted State​

Similar to WinError 5, if a file pip needs to access or modify is locked by another process (Python script, IDE, antivirus), Windows might report it as "not found". Alternatively, a prior failed installation could have left the package directory in a state where files pip expects are missing.

Solution 2: Check Running Processes / Restart / Reinstall​

  • Close Applications: Shut down Python scripts, IDEs, terminals, etc.
  • Check Task Manager (Ctrl+Shift+Esc): Look for running python.exe/pythonw.exe processes.
  • Restart Computer: The simplest way to release file locks. Try pip install immediately after.
  • Uninstall/Reinstall: Try forcefully removing the problematic package and reinstalling it: 
    pip uninstall <package-name>
    pip install <package-name>
    (Use py -m pip etc. if needed).

Other Potential Solutions (Less Common for WinError 2)​

These solutions, often relevant for WinError 5 (Access Denied), might help indirectly with WinError 2 if the root cause involves path issues or subtle permission problems preventing file discovery/access.

Use a Virtual Environment​

Creating a venv in a path with a shorter base (e.g., C:\dev\myproject\venv) can sometimes avoid hitting the MAX_PATH limit compared to installing under the deep AppData path.

Run as Administrator / Use --user Flag​

  • Run as Admin: If installing globally, running Command Prompt/PowerShell as Administrator might bypass certain path restrictions or permission issues. (Use with caution, prefer venvs).
  • --user Flag: pip install <package-name> --user. Installs under your user profile (AppData). While this path can cause long path issues (solved by Solution 1), it avoids needing admin rights for the primary Python installation folders.

Upgrade pip and setuptools​

Ensure core tools are up-to-date: python -m pip install --upgrade pip setuptools wheel.

Manual File/Directory Manipulation (Use with Caution)​

If the error message points to a specific file (like ...dist-info\METADATA) being missing:

  • You could try manually creating an empty METADATA file at that exact location.
  • You could try moving the parent ...dist-info directory temporarily out of site-packages, running pip install again (hoping it recreates it cleanly), and then potentially deleting the moved folder.
note

These are highly specific workarounds for potentially corrupted states and not general solutions.

Check Directory Permissions​

While less likely the direct cause for WinError 2 than WinError 5, ensure your user has adequate permissions (at least Read & Execute, List folder contents) for the parent directories leading up to the path mentioned in the error. Lack of list permissions could theoretically prevent finding a file. (See WinError 5 guide for steps, but apply cautiously).

Conclusion​

The OSError: [WinError 2] The system cannot find the file specified during pip install on Windows most often indicates:

  1. The Windows MAX_PATH limit (260 chars) has been exceeded. Solution: Enable Win32 long paths via the Registry or PowerShell (requires restart).
  2. File locking* by another process or a corrupted package state. Solution: Close running applications, restart the PC, or try uninstalling/reinstalling the specific package.

While other solutions like using virtual environments, running as admin, using --user, or upgrading pip are good general practices and might help in some edge cases related to permissions or path resolution, enabling long path support is the most targeted fix for WinError 2 when long installation paths are involved.

Table of Contents