Resolving the "externally-managed-environment" Error

Overview

The "externally-managed-environment" error occurs when using the latest cimg in CircleCI builds. This error occurs when older versions of the path-filtering and continuation orbs attempt to install Python packages in an environment protected by PEP 668. The newer Python version in the updated image enforces PEP 668, which prevents pip from installing packages directly into system-managed environments.

Prerequisites

• Access to your CircleCI project configuration.
• Familiarity with editing the .circleci/config.yml file.

Solution

The error is linked to older versions of CircleCI orbs that rely on Python scripts. To resolve this, update your orbs to versions that use shell scripts, bypassing PEP 668 restrictions.

1. Open your .circleci/config.yml file.

2. Update the CircleCI orbs in your .circleci/config.yml file to versions that use shell scripts instead of Python:

   From:

3. orbs:
     path-filtering: circleci/path-filtering@1.1.0
     continuation: circleci/continuation@1.0.0

   To:

4. orbs:
     path-filtering: circleci/path-filtering@2
     continuation: circleci/continuation@2

5. Save the changes to your configuration file.

These newer versions have migrated from Python to shell implementations, bypassing PEP 668 restrictions entirely. The update is backward compatible, so existing jobs like path-filtering/set-parameters will continue functioning without modification.

Latest Version can be found on following links

https://circleci.com/developer/orbs/orb/circleci/path-filtering
https://circleci.com/developer/orbs/orb/circleci/continuation

Additional Resources

• CircleCI cimg/node Image Documentation
• CircleCI Path-Filtering Orb
• CircleCI Continuation Orb
• PEP 668 Documentation