如何在pip卸载/升级时清理Python应用的配置文件及目录

方案一：利用pip打包的卸载/升级钩子（直接触发清理） #

pip支持通过setuptools的自定义命令钩子，在卸载或升级时自动执行配置清理操作，完全匹配你要在pip操作时删除旧配置的需求。

实现步骤（基于setuptools） #

在项目的setup.py中添加自定义卸载命令，执行默认卸载流程后清理配置目录：

from setuptools import setup, Command
import os
import shutil
from appdirs import user_config_dir  # 用appdirs统一跨系统配置路径

# 获取应用的标准配置目录（适配Windows/macOS/Linux）
CONFIG_DIR = user_config_dir("your-app-name")

class CustomUninstall(Command):
    description = "Uninstall app and clean up config files"
    user_options = []

    def initialize_options(self):
        pass

    def finalize_options(self):
        pass

    def run(self):
        # 先执行pip默认卸载流程
        self.run_command("uninstall")
        # 清理配置目录
        if os.path.exists(CONFIG_DIR):
            shutil.rmtree(CONFIG_DIR)
            print(f"Removed old config directory: {CONFIG_DIR}")

setup(
    # 你的项目基础配置（name, version, packages等）
    cmdclass={
        "uninstall": CustomUninstall,
    }
)

升级时的自动处理 #

pip升级应用时会先卸载旧版本再安装新版本，旧版本的CustomUninstall钩子会自动触发删除旧配置。新版本安装后，用户首次执行CLI命令时，你的应用代码检测到配置缺失，生成新版本配置即可。

方案二：应用启动时的版本检测（更灵活的替代） #

如果你不想修改打包配置，也可以在应用启动时自动检测配置版本，不匹配则重建配置——这种方式不依赖pip钩子，兼容性更强（比如用户用conda或手动安装时也能生效）。

实现代码示例 #

假设配置用TOML格式存储：

import os
import toml
from your_app import __version__
from appdirs import user_config_dir

CONFIG_DIR = user_config_dir("your-app-name")
CONFIG_PATH = os.path.join(CONFIG_DIR, "config.toml")

def validate_config():
    if os.path.exists(CONFIG_PATH):
        try:
            config = toml.load(CONFIG_PATH)
            # 对比配置版本与当前应用版本
            if config.get("config_version") != __version__:
                os.remove(CONFIG_PATH)
                create_default_config()
        except (toml.TomlDecodeError, KeyError):
            # 配置损坏或无版本信息，直接重建
            create_default_config()
    else:
        create_default_config()

def create_default_config():
    # 创建配置目录（不存在则新建）
    os.makedirs(CONFIG_DIR, exist_ok=True)
    # 写入默认配置及当前版本号
    default_config = {
        "config_version": __version__,
        # 其他默认配置项
        "repo_path": os.path.expanduser("~/local-repos"),
        "log_level": "info"
    }
    with open(CONFIG_PATH, "w") as f:
        toml.dump(default_config, f)

在每个CLI命令的入口函数开头调用validate_config()即可。

两种方案对比 #

注意事项 #

• 用appdirs库获取跨系统的标准配置路径，避免硬编码路径导致的兼容性问题（可通过pip install appdirs安装）
• 如果配置包含用户自定义内容，可在版本检测方案中添加配置迁移逻辑（而非直接删除），比如保留用户自定义项，仅补充新版本的配置项

内容的提问来源于stack exchange，提问作者Germán Navarro Jiménez