Skip to main content

How to Resolve Python Pip "ERROR: Can not perform a '--user' install. User site-packages are not visible in this virtualenv.

When working within an active Python virtual environment (venv or Conda env), attempting to install a package using pip install --user <package-name> will typically result in the error: ERROR: Can not perform a '--user' install. User site-packages are not visible in this virtualenv. This error highlights a conflict between the purpose of virtual environments (isolation) and the --user flag's intention (installing for the user globally).

This guide explains why this error occurs and provides the correct approaches depending on your installation goal.

Understanding the Error: Virtual Environment Isolation vs. --user Installs​

  • Virtual Environments (venv, Conda envs): Designed to create isolated Python environments for specific projects. Packages installed when a venv is active are placed inside that venv's site-packages directory, separate from the global Python installation and other projects. This prevents dependency conflicts. Standard virtual environments deliberately do not see or interact with the user's global site-packages by default.
  • pip install --user: This flag tells pip to install a package into the current user's personal site-packages directory (e.g., ~/.local/lib/pythonX.Y/site-packages or %APPDATA%\Python\...), making it available to that user across different projects outside of specific virtual environments.

The error occurs because these two concepts are usually mutually exclusive by design. When a standard virtual environment is active, pip operates within that isolated environment. The --user flag attempts to force an installation outside this isolated scope into the user's global space, which the active venv cannot (and should not, by default) "see" or manage.

Cause 1: Using the --user Flag Inside an Active Virtual Environment​

This is the most direct cause – you manually typed pip install --user <package-name> while your virtual environment was activated.

Example Error Scenario:

# 1. Activate a virtual environment
(base) C:\Users\User\project> venv\Scripts\activate.bat
(venv) C:\Users\User\project>

# 2. Attempt --user install inside the active venv
(venv) C:\Users\User\project> pip install requests --user
# ⛔️ ERROR: Can not perform a '--user' install. User site-packages are not visible in this virtualenv.

Solution 1: Remove the --user Flag (If Installing into the Venv) (Recommended)​

If your goal is to install the package for the current project within the active virtual environment, simply remove the --user flag. This is the standard way to install packages into a venv.

# Ensure your virtual environment is active
(venv) C:\Users\User\project>

# ✅ Install package INTO the active virtual environment
pip install requests
# Or: python -m pip install requests

# Output should show successful installation within the venv's site-packages.

This correctly installs the package into the isolated environment (venv\Lib\site-packages), which is usually the desired behavior.

Solution 2: Deactivate Venv Before Using --user (If User Install Intended)​

If your intention was actually to install the package globally for your user account (outside of any specific project venv), you need to deactivate the virtual environment first.

# 1. Deactivate the current virtual environment
(venv) C:\Users\User\project> deactivate
C:\Users\User\project>

# 2. Now run the --user install (installs to user's global site-packages)
pip install requests --user
# Or:
python -m pip install requests --user

This correctly performs the user-level installation using your system's default pip (or the one associated with the Python found first in your PATH after deactivation).

Cause 2: IDE/Tool Implicitly Using --user (e.g., VS Code/Pylint Install)​

Sometimes, an IDE or a related tool might attempt a package installation (like installing a linter like pylint when prompted) and might incorrectly add the --user flag even when a virtual environment is active within the IDE's context (e.g., selected interpreter). This triggers the same error.

Solution 3: Configure IDE/Tool Correctly​

If the error appears when your IDE tries to install something:

  • Look for settings within the IDE related to package installation or terminal behavior. Ensure it's not configured to automatically add the --user flag when installing into project environments.
  • Install the required tool (like pylint) manually in the activated virtual environment's terminal within the IDE using pip install pylint (without --user).
  • Ensure the IDE is correctly recognizing and using the Python interpreter from your virtual environment.

Cause 3: Global Pip Configuration (user = true in pip.conf)​

It's possible (though less common) to configure pip globally to always perform user installs by default by setting user = true in its configuration file (pip.conf or pip.ini). This global setting might conflict with the isolated nature of virtual environments.

Solution 4: Check and Modify pip.conf / pip.ini​

  1. Locate pip.conf/pip.ini: The location depends on your OS. Common locations:
    • Linux/macOS: ~/.config/pip/pip.conf, ~/.pip/pip.conf
    • Windows: %APPDATA%\pip\pip.ini, %HOME%\pip\pip.ini (You can often find the user config location by running pip config -v list)
  2. Check for user = true: Open the file and look in the [global] or [install] sections for a line like user = true.
  3. Modify: If found, either comment it out (# user = true) or change it to user = false if you generally don't want default user installs. Save the file.
  4. Retry the installation within your virtual environment (without the --user flag).

Some sources suggest editing the pyvenv.cfg file inside your venv folder and setting include-system-site-packages = true.

  • What it does: This makes packages installed in the global site-packages (including the user site-packages) visible inside your virtual environment. Because the user site-packages are now visible, pip install --user inside the venv might stop erroring (as it sees the target location).
  • Why it's NOT recommended: This breaks the isolation which is the primary benefit of using a virtual environment. It can lead to confusing dependency conflicts between your project's specific needs and globally installed packages. Avoid this setting unless you have a very specific, advanced reason and fully understand the consequences. It doesn't fix the underlying conflict between the intent of --user and the intent of a standard venv.

Conclusion​

The error ERROR: Can not perform a '--user' install. User site-packages are not visible in this virtualenv. occurs because standard virtual environments are isolated and the --user flag tries to install outside that isolation.

The correct solutions depend on your goal:

  1. If installing FOR the project: Activate the virtual environment and run pip install <package-name> (NO --user flag).
  2. If installing GLOBALLY for the user: Deactivate the virtual environment first, then run pip install <package-name> --user.
  3. If an IDE causes the error: Configure the IDE to install packages correctly within the selected virtual environment (usually without --user).
  4. Check pip.conf: Ensure user = true isn't set globally if that's not your desired default behavior.

Do not set include-system-site-packages = true in pyvenv.cfg as a fix for this error, as it compromises the benefits of using a virtual environment.

Table of Contents