Merge 0c7b7994e230f5f8531740f700aeb32a0add5096 into 83679a892e2d95755f2dac6acb0bfd1e9ac5d548

__tests__/clean-pip.test.ts

@@ -0,0 +1,42 @@
+import * as core from '@actions/core';
+import * as exec from '@actions/exec';
+import {cleanPipPackages} from '../src/clean-pip';
+
+describe('cleanPipPackages', () => {
+  let infoSpy: jest.SpyInstance;
+  let setFailedSpy: jest.SpyInstance;
+  let execSpy: jest.SpyInstance;
+
+  beforeEach(() => {
+    infoSpy = jest.spyOn(core, 'info');
+    infoSpy.mockImplementation(() => undefined);
+
+    setFailedSpy = jest.spyOn(core, 'setFailed');
+    setFailedSpy.mockImplementation(() => undefined);
+
+    execSpy = jest.spyOn(exec, 'exec');
+    execSpy.mockImplementation(() => Promise.resolve(0));
+  });
+
+  afterEach(() => {
+    jest.resetAllMocks();
+    jest.clearAllMocks();
+  });
+
+  it('should successfully clean up pip packages', async () => {
+    await cleanPipPackages();
+
+    expect(execSpy).toHaveBeenCalledWith('bash', expect.any(Array));
+    expect(setFailedSpy).not.toHaveBeenCalled();
+  });
+
+  it('should handle errors and set failed status', async () => {
+    const error = new Error('Exec failed');
+    execSpy.mockImplementation(() => Promise.reject(error));
+
+    await cleanPipPackages();
+
+    expect(execSpy).toHaveBeenCalledWith('bash', expect.any(Array));
+    expect(setFailedSpy).toHaveBeenCalledWith('Failed to clean up pip packages.');
+  });
+});

__tests__/post-python.test.ts

@@ -1,7 +1,8 @@
 import * as core from '@actions/core';
 import * as cache from '@actions/cache';
+import * as cleanPip from '../src/clean-pip';
 import * as exec from '@actions/exec';
-import {run} from '../src/cache-save';
+import {run} from '../src/post-python';
 import {State} from '../src/cache-distributions/cache-distributor';
 
 describe('run', () => {
@@ -21,10 +22,13 @@ describe('run', () => {
   let saveStateSpy: jest.SpyInstance;
   let getStateSpy: jest.SpyInstance;
   let getInputSpy: jest.SpyInstance;
+  let getBooleanInputSpy: jest.SpyInstance;
   let setFailedSpy: jest.SpyInstance;
 
   // cache spy
   let saveCacheSpy: jest.SpyInstance;
+  // cleanPipPackages spy
+  let cleanPipPackagesSpy: jest.SpyInstance;
 
   // exec spy
   let getExecOutputSpy: jest.SpyInstance;
@@ -59,6 +63,9 @@ describe('run', () => {
     getInputSpy = jest.spyOn(core, 'getInput');
     getInputSpy.mockImplementation(input => inputs[input]);
 
+    getBooleanInputSpy = jest.spyOn(core, 'getBooleanInput');
+    getBooleanInputSpy.mockImplementation(input => inputs[input]);
+
     getExecOutputSpy = jest.spyOn(exec, 'getExecOutput');
     getExecOutputSpy.mockImplementation((input: string) => {
       if (input.includes('pip')) {
@@ -70,6 +77,9 @@ describe('run', () => {
 
     saveCacheSpy = jest.spyOn(cache, 'saveCache');
     saveCacheSpy.mockImplementation(() => undefined);
+    
+    cleanPipPackagesSpy = jest.spyOn(cleanPip, 'cleanPipPackages');
+    cleanPipPackagesSpy.mockImplementation(() => undefined);
   });
 
   describe('Package manager validation', () => {
@@ -258,6 +268,55 @@ describe('run', () => {
     });
   });
 
+  describe('run with postclean option', () => {
+
+    it('should clean pip packages when postclean is true', async () => {
+      inputs['cache'] = '';
+      inputs['postclean'] = true;
+
+      await run();
+
+      expect(getBooleanInputSpy).toHaveBeenCalledWith('postclean');
+      expect(cleanPipPackagesSpy).toHaveBeenCalled();
+      expect(setFailedSpy).not.toHaveBeenCalled();
+    });
+
+    it('should save cache and clean pip packages when both are enabled', async () => {
+      inputs['cache'] = 'pip';
+      inputs['postclean'] = true;
+      inputs['python-version'] = '3.10.0';
+      getStateSpy.mockImplementation((name: string) => {
+        if (name === State.CACHE_MATCHED_KEY) {
+          return requirementsHash;
+        } else if (name === State.CACHE_PATHS) {
+          return JSON.stringify([__dirname]);
+        } else {
+          return pipFileLockHash;
+        }
+      });
+
+      await run();
+
+      expect(getInputSpy).toHaveBeenCalled();
+      expect(getBooleanInputSpy).toHaveBeenCalledWith('postclean');
+      expect(saveCacheSpy).toHaveBeenCalled();
+      expect(cleanPipPackagesSpy).toHaveBeenCalled();
+      expect(setFailedSpy).not.toHaveBeenCalled();
+    });
+
+    it('should not clean pip packages when postclean is false', async () => {
+      inputs['cache'] = 'pip';
+      inputs['postclean'] = false;
+      inputs['python-version'] = '3.10.0';
+
+      await run();
+
+      expect(getBooleanInputSpy).toHaveBeenCalledWith('postclean');
+      expect(cleanPipPackagesSpy).not.toHaveBeenCalled();
+      expect(setFailedSpy).not.toHaveBeenCalled();
+    });
+  });
+
   afterEach(() => {
     jest.resetAllMocks();
     jest.clearAllMocks();

action.yml

@@ -33,6 +33,12 @@ inputs:
     description: "Used to specify the version of pip to install with the Python. Supported format: major[.minor][.patch]."
   pip-install:
     description: "Used to specify the packages to install with pip after setting up Python. Can be a requirements file or package names."
+  preclean:
+    description: "When 'true', removes all existing pip packages before installing new ones."
+    default: false
+  postclean:
+    description: "When 'true', removes all pip packages installed by this action after the action completes."
+    default: false
 outputs:
   python-version:
     description: "The installed Python or PyPy version. Useful when given a version range as input."
@@ -43,7 +49,7 @@ outputs:
 runs:
   using: 'node24'
   main: 'dist/setup/index.js'
-  post: 'dist/cache-save/index.js'
+  post: 'dist/post-python/index.js'
   post-if: success()
 branding:
   icon: 'code'

dist/post-python/index.js

@@ -87805,7 +87805,69 @@ exports.CACHE_DEPENDENCY_BACKUP_PATH = '**/pyproject.toml';
 
 /***/ }),
 
-/***/ 3579:
+/***/ 8106:
+/***/ (function(__unused_webpack_module, exports, __nccwpck_require__) {
+
+"use strict";
+
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", ({ value: true }));
+exports.cleanPipPackages = cleanPipPackages;
+const core = __importStar(__nccwpck_require__(7484));
+const exec_1 = __nccwpck_require__(5236);
+// Shared helper to uninstall all pip packages in the current environment.
+async function cleanPipPackages() {
+    core.info('Cleaning up pip packages');
+    try {
+        // uninstall all currently installed packages (if any)
+        // Use a shell so we can pipe the output of pip freeze into xargs
+        await (0, exec_1.exec)('bash', [
+            '-c',
+            'test $(which python) != "/usr/bin/python" -a $(python -m pip freeze | wc -l) -gt 0 && python -m pip freeze | xargs python -m pip uninstall -y || true'
+        ]);
+        core.info('Successfully cleaned up pip packages');
+    }
+    catch (error) {
+        core.setFailed('Failed to clean up pip packages.');
+    }
+}
+
+
+/***/ }),
+
+/***/ 3332:
 /***/ (function(__unused_webpack_module, exports, __nccwpck_require__) {
 
 "use strict";
@@ -87850,16 +87912,28 @@ Object.defineProperty(exports, "__esModule", ({ value: true }));
 exports.run = run;
 const core = __importStar(__nccwpck_require__(7484));
 const cache = __importStar(__nccwpck_require__(5116));
+const clean_pip_1 = __nccwpck_require__(8106);
 const fs_1 = __importDefault(__nccwpck_require__(9896));
 const cache_distributor_1 = __nccwpck_require__(2326);
 // Added early exit to resolve issue with slow post action step:
-// - https://github.com/actions/setup-node/issues/878
+// See: https://github.com/actions/setup-node/issues/878
-// https://github.com/actions/cache/pull/1217
+// See: https://github.com/actions/cache/pull/1217
 async function run(earlyExit) {
     try {
         const cache = core.getInput('cache');
-        if (cache) {
+        // Optionally clean up pip packages after the post-action if requested.
-            await saveCache(cache);
+        // This mirrors the `preclean` behavior used in the main action.
+        const postcleanPip = core.getBooleanInput('postclean');
+        if (cache || postcleanPip) {
+            if (cache) {
+                await saveCache(cache);
+            }
+            if (postcleanPip) {
+                await (0, clean_pip_1.cleanPipPackages)();
+            }
+            // Preserve early-exit behavior for the post action when requested.
+            // Some CI setups may want the post step to exit early to avoid long-running
+            // processes during cleanup. If enabled, exit with success immediately.
             if (earlyExit) {
                 process.exit(0);
             }
@@ -87913,7 +87987,9 @@ function isCacheDirectoryExists(cacheDirectory) {
     }, false);
     return result;
 }
-run(true);
+// Invoke the post action runner. No early-exit — this must complete so the cache
+// can be saved during the post step.
+run();
 
 
 /***/ }),
@@ -89867,7 +89943,7 @@ module.exports = /*#__PURE__*/JSON.parse('[[[0,44],"disallowed_STD3_valid"],[[45
 /******/ 	// startup
 /******/ 	// Load entry module and return exports
 /******/ 	// This entry module is referenced by other modules so it can't be inlined
-/******/ 	var __webpack_exports__ = __nccwpck_require__(3579);
+/******/ 	var __webpack_exports__ = __nccwpck_require__(3332);
 /******/ 	module.exports = __webpack_exports__;
 /******/ 	
 /******/ })()

dist/setup/index.js

@@ -96694,6 +96694,68 @@ class PoetryCache extends cache_distributor_1.default {
 exports["default"] = PoetryCache;
 
 
+/***/ }),
+
+/***/ 8106:
+/***/ (function(__unused_webpack_module, exports, __nccwpck_require__) {
+
+"use strict";
+
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", ({ value: true }));
+exports.cleanPipPackages = cleanPipPackages;
+const core = __importStar(__nccwpck_require__(7484));
+const exec_1 = __nccwpck_require__(5236);
+// Shared helper to uninstall all pip packages in the current environment.
+async function cleanPipPackages() {
+    core.info('Cleaning up pip packages');
+    try {
+        // uninstall all currently installed packages (if any)
+        // Use a shell so we can pipe the output of pip freeze into xargs
+        await (0, exec_1.exec)('bash', [
+            '-c',
+            'test $(which python) != "/usr/bin/python" -a $(python -m pip freeze | wc -l) -gt 0 && python -m pip freeze | xargs python -m pip uninstall -y || true'
+        ]);
+        core.info('Successfully cleaned up pip packages');
+    }
+    catch (error) {
+        core.setFailed('Failed to clean up pip packages.');
+    }
+}
+
+
 /***/ }),
 
 /***/ 1663:
@@ -97906,6 +97968,7 @@ const fs_1 = __importDefault(__nccwpck_require__(9896));
 const cache_factory_1 = __nccwpck_require__(665);
 const utils_1 = __nccwpck_require__(1798);
 const exec_1 = __nccwpck_require__(5236);
+const clean_pip_1 = __nccwpck_require__(8106);
 function isPyPyVersion(versionSpec) {
     return versionSpec.startsWith('pypy');
 }
@@ -98007,6 +98070,10 @@ async function run() {
             if (cache && (0, utils_1.isCacheFeatureAvailable)()) {
                 await cacheDependencies(cache, pythonVersion);
             }
+            const precleanPip = core.getBooleanInput('preclean');
+            if (precleanPip) {
+                await (0, clean_pip_1.cleanPipPackages)();
+            }
             const pipInstall = core.getInput('pip-install');
             if (pipInstall) {
                 await installPipPackages(pipInstall);

docs/advanced-usage.md

@@ -24,6 +24,7 @@
 - [Allow pre-releases](advanced-usage.md#allow-pre-releases)
 - [Using the pip-version input](advanced-usage.md#using-the-pip-version-input)
 - [Using the pip-install input](advanced-usage.md#using-the-pip-install-input)
+- [Managing pip packages with preclean and postclean](advanced-usage.md#managing-pip-packages-with-preclean-and-postclean)
 
 ## Using the `python-version` input
 
@@ -692,3 +693,63 @@ The `pip-install` input allows you to install dependencies as part of the Python
 For complex workflows, or alternative package managers (e.g., poetry, pipenv), we recommend using separate steps to maintain clarity and flexibility.
 
 > The `pip-install` input mirrors the flexibility of a standard pip install command and supports most of its arguments.
+
+## Managing pip packages with preclean and postclean
+
+The `preclean` and `postclean` inputs provide control over pip package management during the action lifecycle.
+
+### Using the preclean input
+
+The `preclean` input removes all existing pip packages before installing new ones. This is useful when you want to ensure a clean environment without any pre-existing packages that might conflict with your dependencies.
+
+```yaml
+      steps:
+      - uses: actions/checkout@v5
+      - name: Set up Python
+        uses: actions/setup-python@v6
+        with:
+          python-version: '3.13'
+          pip-install: -r requirements.txt
+          preclean: true
+```
+
+When `preclean` is set to `true`, all pip packages will be removed before any new packages are installed via the `pip-install` input.
+
+### Using the postclean input
+
+The `postclean` input removes all pip packages installed by this action after the action completes. This is useful for cleanup purposes or when you want to ensure that packages installed during setup don't persist beyond the workflow's execution.
+
+```yaml
+      steps:
+      - uses: actions/checkout@v5
+      - name: Set up Python
+        uses: actions/setup-python@v6
+        with:
+          python-version: '3.13'
+          pip-install: pytest requests
+          postclean: true
+      - name: Run tests
+        run: pytest
+```
+
+When `postclean` is set to `true`, packages installed during the setup will be removed after the whole workflow completes successfully.
+
+### Using both preclean and postclean
+
+You can combine both inputs for complete package lifecycle management:
+
+```yaml
+      steps:
+      - uses: actions/checkout@v5
+      - name: Set up Python
+        uses: actions/setup-python@v6
+        with:
+          python-version: '3.13'
+          pip-install: -r requirements.txt
+          preclean: true
+          postclean: true
+      - name: Run your script
+        run: python my_script.py
+```
+
+> Note: Both `preclean` and `postclean` default to `false`. Set them to `true` only when you need explicit package management control.

package.json

@@ -8,12 +8,12 @@
     "node": ">=24.0.0"
   },
   "scripts": {
-    "build": "ncc build -o dist/setup src/setup-python.ts && ncc build -o dist/cache-save src/cache-save.ts",
+    "build": "ncc build -o dist/setup src/setup-python.ts && ncc build -o dist/post-python src/post-python.ts",
     "format": "prettier --no-error-on-unmatched-pattern --config ./.prettierrc.js --write \"**/*.{ts,yml,yaml}\"",
     "format-check": "prettier --no-error-on-unmatched-pattern --config ./.prettierrc.js --check \"**/*.{ts,yml,yaml}\"",
     "lint": "eslint --config ./.eslintrc.js \"**/*.ts\"",
     "lint:fix": "eslint --config ./.eslintrc.js \"**/*.ts\" --fix",
-    "release": "ncc build -o dist/setup src/setup-python.ts && ncc build -o dist/cache-save src/cache-save.ts && git add -f dist/",
+    "release": "ncc build -o dist/setup src/setup-python.ts && ncc build -o dist/post-python src/post-python.ts && git add -f dist/",
     "test": "jest --runInBand --coverage"
   },
   "repository": {

src/clean-pip.ts

@@ -0,0 +1,18 @@
+import * as core from '@actions/core';
+import {exec} from '@actions/exec';
+
+// Shared helper to uninstall all pip packages in the current environment.
+export async function cleanPipPackages() {
+  core.info('Cleaning up pip packages');
+  try {
+    // uninstall all currently installed packages (if any)
+    // Use a shell so we can pipe the output of pip freeze into xargs
+    await exec('bash', [
+      '-c',
+      'test $(which python) != "/usr/bin/python" -a $(python -m pip freeze | wc -l) -gt 0 && python -m pip freeze | xargs python -m pip uninstall -y || true'
+    ]);
+    core.info('Successfully cleaned up pip packages');
+  } catch (error) {
+    core.setFailed('Failed to clean up pip packages.');
+  }
+}

src/post-python.ts

@@ -1,18 +1,30 @@
 import * as core from '@actions/core';
 import * as cache from '@actions/cache';
+import {cleanPipPackages} from './clean-pip';
 
 import fs from 'fs';
 import {State} from './cache-distributions/cache-distributor';
 
 // Added early exit to resolve issue with slow post action step:
-// - https://github.com/actions/setup-node/issues/878
+// See: https://github.com/actions/setup-node/issues/878
-// https://github.com/actions/cache/pull/1217
+// See: https://github.com/actions/cache/pull/1217
 export async function run(earlyExit?: boolean) {
   try {
     const cache = core.getInput('cache');
-    if (cache) {
+    // Optionally clean up pip packages after the post-action if requested.
-      await saveCache(cache);
+    // This mirrors the `preclean` behavior used in the main action.
+    const postcleanPip = core.getBooleanInput('postclean');
 
+    if (cache || postcleanPip) {
+      if (cache) {
+        await saveCache(cache);
+      }
+      if (postcleanPip) {
+        await cleanPipPackages();
+      }
+      // Preserve early-exit behavior for the post action when requested.
+      // Some CI setups may want the post step to exit early to avoid long-running
+      // processes during cleanup. If enabled, exit with success immediately.
       if (earlyExit) {
         process.exit(0);
       }
@@ -84,4 +96,6 @@ function isCacheDirectoryExists(cacheDirectory: string[]) {
   return result;
 }
 
-run(true);
+// Invoke the post action runner. No early-exit — this must complete so the cache
+// can be saved during the post step.
+run();

src/setup-python.ts

@@ -14,6 +14,7 @@ import {
   getVersionsInputFromPlainFile
 } from './utils';
 import {exec} from '@actions/exec';
+import {cleanPipPackages} from './clean-pip';
 
 function isPyPyVersion(versionSpec: string) {
   return versionSpec.startsWith('pypy');
@@ -159,6 +160,10 @@ async function run() {
       if (cache && isCacheFeatureAvailable()) {
         await cacheDependencies(cache, pythonVersion);
       }
+      const precleanPip = core.getBooleanInput('preclean');
+      if (precleanPip) {
+        await cleanPipPackages();
+      }
       const pipInstall = core.getInput('pip-install');
       if (pipInstall) {
         await installPipPackages(pipInstall);