构建与打包 on 扎塔-Zata

npm使用教程

Wed, 16 Jul 2025 00:40:23 +0800

这是一份详细的 npm (Node Package Manager) 使用教程，从入门基础到高级技巧和最佳实践，希望能帮助你完全掌握这个强大的工具。

常用命令

以下是最常用的 npm 命令：

命令	别名	说明	示例
`npm install`	`npm i`	安装项目依赖	`npm install`
`npm install <package>`	`npm i <package>`	安装特定包	`npm install lodash`
`npm install <package> --save-dev`	`npm i <package> -D`	安装开发依赖	`npm install jest -D`
`npm uninstall <package>`	`npm un <package>`	卸载包	`npm uninstall lodash`
`npm update`	-	更新包	`npm update`
`npm init`	-	初始化项目	`npm init`
`npm init -y`	-	快速初始化	`npm init -y`
`npm start`	-	启动应用	`npm start`
`npm test`	-	运行测试	`npm test`
`npm run <script>`	-	运行脚本	`npm run dev`
`npm list`	`npm ls`	查看已安装的包	`npm list --depth=0`
`npm outdated`	-	检查过时的包	`npm outdated`
`npm audit`	-	安全漏洞检查	`npm audit`
`npm audit fix`	-	修复安全漏洞	`npm audit fix`
`npx <package>`	-	执行包而不安装	`npx create-react-app my-app`

快速参考

# 初始化项目
npm init -y

# 安装依赖
npm install [--legacy-peer-deps]

# 安装/卸载包
npm install <包名>
npm install <包名> --save-dev
npm uninstall <包名>

# 运行脚本
npm start
npm run dev
npm test

# 查看/更新/安全
npm list --depth=0
npm outdated
npm update
npm audit
npm audit fix

1. 什么是 npm？

npm (Node Package Manager) 是 Node.js 的默认包管理器。它主要有两个功能：

命令行工具 (CLI): 一个安装在你电脑上的命令行工具，用于安装、管理和发布 JavaScript 包。
在线仓库 (Registry): 一个巨大的公共在线数据库，存放了成千上万个可重用的 JavaScript 代码包（也称为模块或依赖）。

简单来说，当你需要一个特定功能（比如处理日期、发送网络请求）时，你不需要从零开始写，可以直接从 npm 仓库下载别人已经写好的包，并在你的项目中使用。

2. 安装 npm

npm 是随 Node.js 一起安装的。所以，你只需要安装 Node.js，npm 就会自动安装好。

访问 Node.js 官方网站。
下载推荐的 LTS (Long Term Support) 版本并安装。
安装完成后，打开你的终端（在 Windows 上是 Command Prompt 或 PowerShell，在 macOS/Linux 上是 Terminal），运行以下命令来验证安装：

# 查看 Node.js 版本
node -v

# 查看 npm 版本
npm -v

如果能看到版本号，说明安装成功。

3. 核心概念

理解这三个文件/文件夹是掌握 npm 的关键。

package.json
- 是什么：项目的"身份证"或"说明书"。它是一个 JSON 格式的配置文件，位于项目的根目录。
- 作用：定义了项目的名称、版本、作者等元数据，并且最重要的是，它记录了项目需要哪些依赖包（dependencies）和开发过程中需要哪些依赖包（devDependencies）。
node_modules
- 是什么：存放所有项目依赖的文件夹。
- 作用：当你使用 npm install 命令时，npm 会根据 package.json 的记录，从 npm 仓库下载所有需要的包，并存放在这个文件夹里。这个文件夹通常非常大，不应该提交到版本控制系统（如 Git）中。
package-lock.json
- 是什么：锁定依赖版本的"快照"文件。
- 作用：它精确地记录了 node_modules 文件夹中每个包的确切版本及其依赖树。这确保了团队中每个成员以及在服务器上部署时，安装的依赖版本都是完全一致的，避免了"在我电脑上能跑"的问题。这个文件应该提交到版本控制系统。

4. 常用命令详解

`npm init`

用于初始化一个新的 Node.js 项目，它会引导你创建一个 package.json 文件。

# 创建一个新文件夹并进入
mkdir my-project
cd my-project

# 运行初始化命令
npm init

系统会问你一系列问题（项目名称、版本、描述等），你可以一路按回车使用默认值。

如果你想快速生成一个默认的 package.json，可以使用 -y 标志：

npm init -y

`npm install`

这是最核心、最常用的命令。

别名: npm i
安装项目所有依赖: 如果你的项目里已经有 package.json 和 package-lock.json 文件，直接运行：
```
npm install
```
npm 会读取 package-lock.json 并安装所有依赖到 node_modules 文件夹。

安装特定包:

# 安装一个包，并将其添加到 "dependencies" (生产环境依赖)
npm install lodash

# 安装一个包，并将其添加到 "devDependencies" (开发环境依赖)
# 比如测试工具、打包工具等
npm install jest --save-dev
# 或者使用简写
npm install jest -D

dependencies vs devDependencies

dependencies: 你的应用在生产环境中运行时必须的包（如 React, Express）。

devDependencies: 只在开发和构建过程中需要的包（如 Webpack, ESLint, Jest）。

全局安装: 有些包是命令行工具（比如 nodemon），需要全局安装才能在任何地方使用。
```
npm install -g nodemon
```
注意: 尽量避免过多全局安装，优先使用 npx (后面会讲)。

以下是与依赖管理和冲突解决相关的常用参数：

参数	说明	对你的错误的适用场景
`--legacy-peer-deps`	忽略 peer dependency 冲突，使用旧版 npm 的解析逻辑。	绕过 `typescript` 与 `react-scripts` 的版本冲突。
`--force`	强制安装，覆盖依赖冲突，可能忽略合法约束。	作为最后手段解决无法解析的冲突。
`--save`	将包保存到 `package.json` 的 `dependencies` 中（npm < 7 默认行为）。	添加新包时使用，非直接相关。
`--save-dev`	将包保存到 `package.json` 的 `devDependencies` 中。	安装 `typescript` 作为开发依赖时使用。
`--no-audit`	跳过依赖的安全审计。	加速安装，减少审计相关的延迟。
`--no-fund`	抑制 npm 的资助提示信息。	提高输出日志的可读性。
`--verbose`	提供详细的安装日志输出。	调试安装问题时查看更多日志信息。
`--production`	仅安装 `dependencies`（跳过 `devDependencies`）。	生产环境部署时使用，与此问题无关。
`--cache=<path>`	指定自定义缓存目录。	缓存问题持续存在时使用，较少需要。

`npm uninstall`

用于卸载一个包。

别名: npm un

# 卸载一个包，并将其从 package.json 中移除
npm uninstall lodash

# 卸载一个开发依赖
npm uninstall jest --save-dev
# 或
npm uninstall jest -D

`npm update`

用于将包更新到 package.json 中指定的版本范围内的最新版本。

# 更新所有包
npm update

# 只更新特定的包
npm update lodash

注意: npm update 比较保守，它会遵守 package.json 中的版本规则（如 ^ 或 ~）。它不会将包升级到一个新的主版本（Major version）。

`npm run`

用于运行在 package.json 文件中 scripts 部分定义的脚本。

假设你的 package.json 如下：

{
 "scripts": {
 "start": "node index.js",
 "test": "jest",
 "build": "webpack"
 }
}

你可以这样运行脚本：

# 运行 start 脚本
npm run start
# 对于 "start", "test", "stop", "restart"，可以省略 run
npm start

# 运行 test 脚本
npm test

# 运行 build 脚本
npm run build

`npm list`

用于查看当前项目安装了哪些包，以及它们的依赖关系。

# 查看所有一级包
npm list --depth=0

# 查看全局安装的包
npm list -g --depth=0

5. 深入理解 `package.json`

一个典型的 package.json 文件结构：

{
 "name": "my-project",
 "version": "1.0.0",
 "description": "A simple project.",
 "main": "index.js",
 "scripts": {
 "start": "node index.js"
 },
 "keywords": ["tutorial", "npm"],
 "author": "Your Name",
 "license": "ISC",
 "dependencies": {
 "express": "^4.18.2"
 },
 "devDependencies": {
 "nodemon": "^2.0.22"
 }
}

"name": 包的名称，必须是唯一的、小写的，不能有空格。
"version": 当前版本号，遵循语义化版本。
"description": 项目描述。
"main": 项目的入口文件。
"scripts": 定义可执行的脚本命令。
"dependencies": 生产环境依赖。
"devDependencies": 开发环境依赖。

6. 版本管理：语义化版本 (SemVer)

npm 使用语义化版本来管理包的版本。版本号格式为 主版本号.次版本号.修订号 (MAJOR.MINOR.PATCH)。

MAJOR: 当你做了不兼容的 API 修改。
MINOR: 当你做了向下兼容的功能性新增。
PATCH: 当你做了向下兼容的问题修正。

在 package.json 中，你经常会看到版本号前面有 ^ 或 ~：

^ (Caret): 锁定主版本号，允许次版本号和修订号更新。例如 ^4.18.2 匹配 >=4.18.2 且 <5.0.0 的所有版本。这是 npm install <package> 的默认行为。
~ (Tilde): 锁定主版本号和次版本号，只允许修订号更新。例如 ~4.18.2 匹配 >=4.18.2 且 <4.19.0 的所有版本。

7. 进阶命令

`npm outdated`

检查哪些包已经过时了，可以更新。

npm outdated

它会列出当前版本、期望版本和最新版本，非常方便。

`npm ci`

这个命令用于持续集成 (Continuous Integration, CI) 环境，比如在 Jenkins 或 GitHub Actions 中。

npm ci

它和 npm install 的区别：

严格: 它完全根据 package-lock.json 来安装，如果 package.json 和 package-lock.json 不一致，它会报错退出。
快速: 它会先删除现有的 node_modules，然后进行一次全新的、干净的安装，通常比 npm install 更快。
确定性: 保证了在任何机器上安装的依赖都是完全一致的。

最佳实践: 在开发时使用 npm install，在自动化构建和部署时使用 npm ci。

`npm audit`

扫描你的项目依赖，查找已知的安全漏洞。

npm audit

如果发现漏洞，它会提供报告，并可能提供修复命令：

npm audit fix

`npm view`

在不安装的情况下，查看一个包的详细信息。

别名: npm v

# 查看 React 的所有版本
npm view react versions

# 查看 Express 的最新版本信息
npm view express

`npx`

一个非常有用的工具，它允许你执行一个 npm 包的命令，而不需要全局安装它。

场景: 假设你想用 create-react-app 创建一个新的 React 项目。

旧方式 (不推荐): npm install -g create-react-app，然后 create-react-app my-app。这会把 create-react-app 全局安装在你的系统里，可能很快就过时了。
新方式 (推荐):
```
npx create-react-app my-app
```
npx 会临时下载最新版的 create-react-app，运行它，然后在命令结束后清理掉，不会污染你的全局环境。

8. 最佳实践和技巧

始终提交 package-lock.json: 确保团队协作和部署的一致性。
使用 .npmrc 文件: 你可以在项目根目录或用户主目录下创建一个 .npmrc 文件来配置 npm 的行为，比如设置私有仓库地址：registry=https://registry.npm.taobao.org (如果你在中国，这可以加速下载)。
优先使用 npx: 对于一次性的脚手架工具或不常用的命令，使用 npx 而不是全局安装。
定期运行 npm outdated 和 npm audit: 保持你的依赖更新并关注安全问题。
理解 dependencies 和 devDependencies 的区别: 将包正确地归类，可以减小生产环境安装包的体积。

npm 相关问题解决教程

1. 前端启动问题

问题现象

运行 npm run dev 后，虽然显示服务器启动成功：

VITE v4.5.14 ready in 123 ms
➜ Local: http://localhost:3000/
➜ Network: use --host to expose

但访问 http://localhost:3000 时出现：

ERR_EMPTY_RESPONSE
127.0.0.1 未发送任何数据

解决方案

临时解决方案

npm run dev -- --host 0.0.0.0

永久解决方案1：修改 package.json（推荐）

{
 "scripts": {
 "dev": "vite --host 0.0.0.0",
 "start": "vite --host 0.0.0.0",
 "build": "tsc && vite build",
 "lint": "eslint . --ext ts,tsx --report-unused-disable-directives --max-warnings 0",
 "preview": "vite preview"
 }
}

永久解决方案2：修改 vite.config.ts

import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'
import path from 'path'

export default defineConfig({
 plugins: [react()],
 resolve: {
 alias: {
 '@': path.resolve(__dirname, './src'),
 },
 },
 server: {
 host: '0.0.0.0', // 添加这行
 port: 3000,
 proxy: {
 '/api': {
 target: 'http://localhost:8000',
 changeOrigin: true,
 secure: false,
 },
 },
 },
})

永久解决方案3：使用环境变量

创建 frontend/.env 文件：

VITE_HOST=0.0.0.0
VITE_PORT=3000

然后在 vite.config.ts 中使用：

export default defineConfig({
 // ... 其他配置
 server: {
 host: process.env.VITE_HOST || '0.0.0.0',
 port: Number(process.env.VITE_PORT) || 3000,
 // ... 其他配置
 },
})

2. npm 脚本命令详解

内置脚本 vs 自定义脚本

内置脚本（不需要 `run`）

npm start # 启动应用
npm test # 运行测试
npm stop # 停止应用
npm restart # 重启应用
npm install # 安装依赖
npm uninstall # 卸载依赖
npm update # 更新依赖
npm publish # 发布包
npm version # 版本管理
npm pack # 打包

自定义脚本（必须使用 `run`）

npm run dev # 开发模式
npm run build # 构建生产版本
npm run lint # 代码检查
npm run preview # 预览构建结果

为什么 `npm start` 不需要 `run`？

历史原因：start 和 test 是最常用的命令，npm 从早期就支持直接调用
简化常用操作：启动和测试是最频繁的操作，简化输入提高效率
标准化约定：所有 npm 包都遵循这个约定

实际验证

# 这些命令完全等效
npm start === npm run start
npm test === npm run test

# 但是 npm 允许省略 run（仅限内置脚本）
npm start # ✅ 推荐写法
npm test # ✅ 推荐写法

3. 常用 npm 脚本配置

基础配置

{
 "scripts": {
 "dev": "vite --host 0.0.0.0",
 "start": "vite --host 0.0.0.0",
 "build": "tsc && vite build",
 "lint": "eslint . --ext ts,tsx --report-unused-disable-directives --max-warnings 0",
 "preview": "vite preview"
 }
}

进阶配置

{
 "scripts": {
 "dev": "vite --host 0.0.0.0",
 "start": "npm run dev",
 "build": "tsc && vite build",
 "build:prod": "NODE_ENV=production npm run build",
 "preview": "vite preview",
 "lint": "eslint . --ext ts,tsx",
 "lint:fix": "eslint . --ext ts,tsx --fix",
 "test": "vitest",
 "test:watch": "vitest --watch",
 "clean": "rm -rf dist node_modules/.vite",
 "reinstall": "rm -rf node_modules package-lock.json && npm install"
 }
}

4. 常见问题排查

端口占用问题

# 检查端口占用
lsof -i :3000
netstat -tlnp | grep :3000

# 杀死占用端口的进程
kill -9 <PID>

清除缓存

# 清除 npm 缓存
npm cache clean --force

# 清除 Vite 缓存
rm -rf node_modules/.vite

# 完全重新安装
rm -rf node_modules package-lock.json
npm install

网络问题

# 测试本地连接
curl -I http://localhost:3000
curl -I http://127.0.0.1:3000
curl -I http://0.0.0.0:3000

5. 脚本最佳实践

脚本命名约定

{
 "scripts": {
 "start": "启动应用（通常是生产环境）",
 "dev": "开发模式启动",
 "build": "构建生产版本",
 "build:dev": "构建开发版本",
 "build:prod": "构建生产版本",
 "test": "运行测试",
 "test:watch": "监听模式运行测试",
 "lint": "代码检查",
 "lint:fix": "代码检查并自动修复",
 "preview": "预览构建结果",
 "clean": "清理构建文件"
 }
}

参数传递

# 向脚本传递参数
npm run dev -- --port 3001
npm run build -- --mode production

# 在 package.json 中使用参数
"dev": "vite --host 0.0.0.0 --port 3000"

6. 问题解决总结

问题核心：Vite 默认只绑定 localhost，需要添加 --host 0.0.0.0
推荐方案：直接在 package.json 中配置参数
npm 命令：内置脚本不需要 run，自定义脚本需要 run
最佳实践：使用标准的脚本命名约定，方便团队协作

包管理工具poetry使用教程

Tue, 13 May 2025 17:59:15 +0800

Poetry 是一个 Python 的依赖管理和项目打包工具，旨在简化 Python 项目的工作流程。本教程将涵盖安装、基本使用、常见命令和一些实用技巧，适合初学者和有一定经验的用户。

1. 什么是 Poetry？

Poetry 是一个用于管理 Python 项目依赖、虚拟环境和打包的工具。它通过一个 pyproject.toml 文件统一管理项目的元数据、依赖和构建配置。相比传统的 pip 和 requirements.txt，Poetry 提供了更现代化的工作流。

主要特点：

自动管理虚拟环境
精确的依赖解析，避免版本冲突
简化的项目打包和发布流程
支持 pyproject.toml，符合 PEP 517/518 标准

2. 安装 Poetry

2.1 安装 Poetry

在 Linux、macOS 或 Windows（推荐使用 WSL 或 PowerShell）上，可以通过以下命令安装 Poetry：

curl -sSL https://install.python-poetry.org | python3 -

或者使用 pip（不推荐，但可用）：

pip install poetry

2.2 验证安装

安装完成后，检查 Poetry 版本：

poetry --version

输出类似：Poetry (version 1.8.3) 表示安装成功。

2.3 配置 Poetry

默认情况下，Poetry 会在每个项目中创建虚拟环境。你可以配置全局设置，例如让虚拟环境存储在项目目录内：

poetry config virtualenvs.in-project true

查看所有配置：

poetry config --list

3. 创建一个新项目

3.1 初始化项目

在终端中，创建一个新项目：

poetry new my-project

这会生成以下目录结构：

my-project/
├── pyproject.toml # 项目配置文件
├── README.md # 项目说明文件
├── my_project/ # 代码目录
│ └── __init__.py
└── tests/ # 测试目录
 └── __init__.py

3.2 使用现有项目

如果你有一个现有的 Python 项目，可以进入项目目录并初始化 Poetry：

cd my-existing-project
poetry init

这会引导你交互式地创建 pyproject.toml 文件，输入项目名称、版本、依赖等信息。

4. 管理依赖

4.1 添加依赖

使用 poetry add 安装依赖并自动更新 pyproject.toml 和 poetry.lock 文件。例如，安装 requests：

poetry add requests

指定版本：

poetry add requests@^2.28.0

开发依赖（仅用于开发环境，例如测试工具）：

poetry add pytest --group dev

4.2 移除依赖

移除某个依赖：

poetry remove requests

4.3 查看依赖

列出所有已安装的依赖：

poetry show

显示依赖树：

poetry show --tree

4.4 锁定依赖

Poetry 使用 poetry.lock 文件锁定依赖的确切版本，确保一致性。更新锁文件：

poetry lock

如果只想更新依赖到最新兼容版本：

poetry update

5. 管理虚拟环境

5.1 激活虚拟环境

Poetry 自动为项目创建虚拟环境。激活虚拟环境：

poetry shell

退出虚拟环境：

exit

5.2 在虚拟环境中运行命令

不进入 shell 也可以直接运行命令：

poetry run python my_script.py

运行测试（例如使用 pytest）：

poetry run pytest

5.3 检查虚拟环境

查看当前虚拟环境路径：

poetry env info

列出所有虚拟环境：

poetry env list

删除虚拟环境：

poetry env remove python3.10

6. 打包和发布项目

6.1 配置项目

编辑 pyproject.toml，确保 [tool.poetry] 部分包含正确的元数据，例如：

[tool.poetry]
name = "my-project"
version = "0.1.0"
description = "A sample Python project"
authors = ["Your Name <your.email@example.com>"]
readme = "README.md"

[tool.poetry.dependencies]
python = "^3.8"
requests = "^2.28.0"

[tool.poetry.group.dev.dependencies]
pytest = "^7.2.0"

6.2 构建项目

生成项目的 wheel 或 sdist 文件：

poetry build

输出文件会出现在 dist/ 目录中，例如：

dist/
├── my_project-0.1.0-py3-none-any.whl
├── my_project-0.1.0.tar.gz

6.3 发布到 PyPI

配置 PyPI 的 token（在 PyPI 官网生成）：

poetry config pypi-token.pypi your-api-token

发布项目：

poetry publish

如果发布到测试 PyPI：

poetry publish --repository testpypi

7. 常用命令速查

命令	功能
`poetry new <name>`	创建新项目
`poetry init`	初始化现有项目
`poetry add <package>`	添加依赖
`poetry remove <package>`	移除依赖
`poetry install`	安装所有依赖
`poetry update`	更新依赖到最新兼容版本
`poetry lock`	锁定依赖版本
`poetry shell`	进入虚拟环境
`poetry run <command>`	在虚拟环境中运行命令
`poetry build`	构建项目
`poetry publish`	发布项目到 PyPI
`poetry env info`	查看虚拟环境信息

8. 实用技巧

8.1 使用特定 Python 版本

如果系统中安装了多个 Python 版本，可以指定 Poetry 使用的版本：

poetry env use python3.10

8.2 导出 requirements.txt

如果需要与不支持 Poetry 的工具兼容，可以导出依赖：

poetry export -f requirements.txt --output requirements.txt

8.3 管理多个依赖组

Poetry 支持依赖分组。例如，添加文档生成工具到 docs 组：

poetry add sphinx --group docs

安装特定组的依赖：

poetry install --only docs

8.4 解决依赖冲突

如果依赖解析失败，检查 poetry.lock 或运行：

poetry lock --no-update

8.5 集成 IDE

大多数现代 IDE（如 PyCharm、VS Code）支持 Poetry。确保 IDE 指向 Poetry 创建的虚拟环境路径（通过 poetry env info 查看）。

9. 常见问题

9.1 Poetry 安装依赖很慢？

尝试设置国内镜像（例如清华源）：

poetry config pypi-mirror https://pypi.tuna.tsinghua.edu.cn/simple

9.2 虚拟环境未激活？

确保运行 poetry shell 或 poetry run。如果仍无效，检查是否正确安装了 Python 和 Poetry。

9.3 如何升级 Poetry？

升级到最新版本：

poetry self update

10. 资源推荐

官方文档：https://python-poetry.org/docs/
PyPI：https://pypi.org/
Poetry GitHub：https://github.com/python-poetry/poetry
社区讨论：在 X 平台搜索 #Poetry 或 #Python 获取最新动态

Poetry 和 uv

以下是对 Poetry 和 uv 的对比分析，帮你理解它们的相似点和不同点。

1. 相似点

Poetry 和 uv 都是现代化的 Python 工具，旨在改进传统的 pip 和 requirements.txt 工作流。它们的共同点包括：

依赖管理：两者都提供依赖解析和锁定功能，生成精确的依赖文件（Poetry 用 poetry.lock，uv 用 uv.lock）。
虚拟环境：自动创建和管理虚拟环境，隔离项目依赖。
项目配置：基于 pyproject.toml 文件管理项目元数据和依赖，符合 PEP 517/518。
命令行接口：提供简洁的 CLI 命令（如 add、install、run）来管理依赖和运行脚本。
打包支持：都支持构建和发布 Python 包到 PyPI。
现代化体验：目标是简化工作流，解决 pip 的依赖冲突和环境管理问题。

这些相似点让你感觉它们“很像”，因为它们都在解决 Python 生态中类似的问题。

2. 不同点

尽管功能上有重叠，Poetry 和 uv 在设计理念、性能和使用场景上有显著差异：

2.1 设计理念

Poetry：
- 专注于 Python 项目的全生命周期管理，包括依赖管理、虚拟环境、打包和发布。
- 强调用户友好和跨平台一致性，适合开发者和小型团队。
- 提供一体化的工作流，适合需要从项目创建到发布的完整工具链的场景。
uv：
- 由 Astral 团队（Ruff 开发者）开发，定位为高性能的 Python 工具链。
- 更专注于速度和效率，用 Rust 编写，解析和安装依赖的速度远超 Poetry。
- 设计上更模块化，适合需要快速迭代或大型项目的高级用户。

2.2 性能

Poetry：
- 使用 Python 编写，依赖解析和安装速度相对较慢，尤其在复杂项目中。
- 依赖解析有时会因兼容性检查而耗时。
uv：
- 用 Rust 编写，依赖解析和安装速度极快（官方宣称比 Poetry 快 10-100 倍）。
- 优化了缓存和并行下载，适合 CI/CD 和大规模项目。

2.3 功能侧重

Poetry：
- 提供内置的项目初始化（poetry new）和发布工具（poetry publish）。
- 支持依赖分组（如 dev、docs），方便管理不同用途的依赖。
- 更适合小型到中型项目或需要简单配置的开发者。
uv：
- 提供更灵活的工具链，包括依赖管理、脚本运行、Python 版本管理和项目工作流。
- 支持工作空间（workspaces），适合管理 monorepo 或多项目结构。
- 更适合高级用户或需要高性能的场景，如 CI/CD 流水线或大型项目。

2.4 虚拟环境管理

Poetry：
- 自动为每个项目创建虚拟环境，默认存储在全局缓存目录（可配置为项目内）。
- 使用 poetry shell 进入虚拟环境，体验类似传统虚拟环境。
uv：
- 虚拟环境管理更轻量，创建速度更快，默认存储在项目目录下的 .venv。
- 支持直接运行命令（uv run）而无需显式激活环境，简化工作流。

2.5 依赖解析

Poetry：
- 使用 poetry.lock 锁定依赖版本，解析过程较为严格，确保跨环境一致性。
- 依赖解析有时过于谨慎，可能拒绝安装不完全兼容的版本。
uv：
- 使用 uv.lock（基于 lockfiles 的新标准），解析更灵活且速度更快。
- 支持增量解析，在 CI/CD 中减少重复工作。

2.6 生态集成

Poetry：
- 与现有 Python 生态（如 PyPI、pytest）集成良好，社区成熟。
- 对 IDE（如 PyCharm、VS Code）的支持更友好，配置简单。
uv：
- 生态还在快速发展，部分功能（如发布工具）不如 Poetry 成熟。
- 与 Ruff（Astral 的代码检查工具）深度集成，适合追求全栈 Rust 工具链的用户。

2.7 学习曲线和社区

Poetry：
- 文档全面，社区活跃，学习曲线较平缓。
- 适合初学者和需要稳定工具的开发者。
uv：
- 文档正在完善，功能迭代很快，可能需要更多摸索。
- 更适合有经验的开发者或愿意尝试新工具的用户。

3. 代码示例对比

为了直观感受它们的相似与不同，下面是对常见任务的命令对比：

3.1 创建项目

Poetry：
```
poetry new my-project
cd my-project
```
生成带 pyproject.toml 的项目结构。
uv：
```
uv init my-project
cd my-project
```
生成简化的项目结构，包含 pyproject.toml。

3.2 添加依赖

Poetry：
```
poetry add requests
```
更新 pyproject.toml 和 poetry.lock。
uv：
```
uv add requests
```
更新 pyproject.toml 和 uv.lock，速度更快。

3.3 运行脚本

Poetry：

poetry run python my_script.py

或进入虚拟环境：

poetry shell
python my_script.py

uv：
```
uv run python my_script.py
```
无需显式激活虚拟环境。

3.4 锁定依赖

Poetry：
```
poetry lock
```
uv：
```
uv lock
```

3.5 安装依赖

Poetry：
```
poetry install
```
uv：
```
uv sync
```

4. 为什么感觉很像？

你感觉 Poetry 和 uv 很像，可能因为：

两者都使用 pyproject.toml 作为核心配置文件，命令结构类似（add、run 等）。
都旨在取代 pip 和 virtualenv，提供更现代的工作流。
在基本操作（如添加依赖、运行脚本）上，命令和输出体验接近。

但 uv 的高性能（得益于 Rust）和模块化设计使其更像一个“下一代”工具，而 Poetry 更像一个成熟的“全家桶”解决方案。

5. 选择哪个？

选择 Poetry 如果：

你想要一个稳定、成熟的工具，文档和社区支持完善。
你是初学者或需要简单的项目管理流程。
你重视跨平台一致性和发布到 PyPI 的便捷性。
你不需要极致的性能，中小型项目足够。

选择 uv 如果：

你追求高性能，特别是在 CI/CD 或大型项目中。
你需要管理复杂项目结构（如 monorepo）。
你愿意尝试新工具并接受快速迭代的生态。
你已经使用 Ruff 或其他 Astral 工具，想保持工具链一致。

6. 总结

Poetry 和 uv 在功能上有重叠，都简化了 Python 依赖管理和项目工作流，但它们的侧重点不同：

Poetry：成熟、用户友好，适合中小型项目和完整工作流。
uv：高性能、模块化，适合高级用户和大规模项目。

如果你刚开始，Poetry 可能更易上手；如果你追求速度或复杂项目管理，uv 可能是更好的选择。可以根据项目需求尝试两者，甚至在不同项目中混用（不过要注意虚拟环境隔离）。

如果你有具体场景（比如某个任务想对比 Poetry 和 uv 的用法），可以告诉我，我可以进一步细化说明！

pipx使用教程

Mon, 12 May 2025 14:32:42 +0800

参考：

https://pipx.pypa.io/stable

https://zhuanlan.zhihu.com/p/637791135

https://www.kancloud.cn/madxzb/python-guide/2248088

pipx 是一个帮助你安装和运行 Python 终端应用的工具，它的主要优点是能将这些应用安装在独立隔离的环境中，避免与系统或其他项目的 Python 包产生冲突。

`pipx` 的核心优势：

隔离性： 每个通过 pipx 安装的应用都有自己独立虚拟环境，这意味着它们的依赖项不会影响到你的全局 Python 环境或其他项目。
便利性： 可以轻松地运行 Python 应用，而无需手动创建和管理虚拟环境。
安全性： 减少了全局安装 Python 包可能带来的风险。
简洁性： 专注于应用本身，而不是其复杂的依赖关系。

教程大纲：

安装 pipx
pipx 的基本使用
- 安装 Python 应用
- 运行应用
- 列出已安装的应用
- 升级应用
- 卸载应用
- 运行一次性的应用 (使用 pipx run)
pipx 的进阶使用
- 管理 pipx 环境
- 自定义 pipx 安装位置
- 注入额外的包到应用环境中
常用命令总结

1. 安装 `pipx`

pipx 本身也是一个 Python 包，你可以使用 pip 来安装它。

如果你使用的是 Python 3.6 或更高版本 (推荐)：
```
python3 -m pip install --user pipx
python3 -m pipx ensurepath
```
--user 参数会将 pipx 安装在你的用户目录下，而不是系统全局目录。pipx ensurepath 命令会确保 pipx 安装的可执行文件路径被添加到你的系统 PATH 环境变量中。执行完此命令后，你可能需要重启你的终端或者重新加载你的 shell 配置文件 (例如 .bashrc, .zshrc) 才能让 PATH 的改动生效。
使用包管理器 (例如 Homebrew on macOS, apt on Debian/Ubuntu)：
- macOS (使用 Homebrew):
```
brew install pipx
pipx ensurepath
```
- Debian/Ubuntu (可能需要较新版本)：
```
sudo apt update
sudo apt install pipx
pipx ensurepath
```
  (注意：通过系统包管理器安装的版本可能不是最新的。)
验证安装：

打开一个新的终端窗口，然后输入：
```
pipx --version
```
如果安装成功，你会看到 pipx 的版本号。

2. `pipx` 的基本使用

2.1 安装 Python 应用

使用 pipx install <package_name> 命令来安装一个 Python 应用。pipx 会自动为这个应用创建一个新的隔离环境，并将应用的可执行文件链接到 ~/.local/bin (默认情况下)。

示例： 安装 cowsay (一个经典的终端程序)

pipx install cowsay

示例： 安装 youtube-dl 或其现代替代品 yt-dlp (一个视频下载工具)

pipx install yt-dlp

示例： 安装 black (一个 Python 代码格式化工具)

pipx install black

安装完成后，如果 ~/.local/bin 在你的 PATH 中，你就可以直接在终端运行这些应用了。

2.2 运行应用

一旦通过 pipx 安装了应用，你就可以像运行其他任何终端命令一样运行它。

示例：

cowsay "Hello from pipx!"
yt-dlp --version
black --version

2.3 列出已安装的应用

要查看所有通过 pipx 安装的应用及其环境信息，使用：

pipx list

输出会显示每个应用的版本、Python 版本、可执行文件路径等。

2.4 升级应用

升级单个应用：

pipx upgrade <package_name>

例如，升级 yt-dlp:

pipx upgrade yt-dlp

升级所有已安装的应用：
```
pipx upgrade-all
```

2.5 卸载应用

要移除一个通过 pipx 安装的应用及其隔离环境，使用：

pipx uninstall <package_name>

例如，卸载 cowsay:

pipx uninstall cowsay

2.6 运行一次性的应用 (使用 pipx run)

如果你只是想临时运行一个 Python 应用，而不想永久安装它，可以使用 pipx run 命令。pipx 会在一个临时的虚拟环境中下载并运行该应用，运行结束后会自动清理环境。

这对于那些你不经常使用，或者只是想尝试一下的工具非常有用。

示例：

运行 cowsay 并传递参数，而无需先 pipx install cowsay:
```
pipx run cowsay "Temporary moo"
```
运行一个简单的 HTTP 服务器 (Python 内置的 http.server 模块)：
```
pipx run http.server -- --directory /path/to/your/files 8000
```
注意：当应用本身也需要接收参数时，你可能需要在应用参数前加上 --，以告诉 pipx 后面的参数是给应用而不是给 pipx run 命令的。
运行特定版本的应用：
```
pipx run black==22.3.0 --check .
```

3. `pipx` 的进阶使用

3.1 管理 pipx 环境

重新安装所有包： 如果 pipx 的内部结构或 Python 版本发生变化，你可能需要重新安装所有应用。
```
pipx reinstall-all
```
查看某个应用的详细信息：
```
pipx list --include-injected <package_name>
```
这会显示应用的安装路径、Python 版本以及任何通过 pipx inject 注入的额外包。

3.2 自定义 pipx 安装位置

默认情况下，pipx 将环境安装在 ~/.local/pipx/venvs，可执行文件链接到 ~/.local/bin。你可以通过环境变量来修改这些路径：

PIPX_HOME: 定义 pipx 安装环境和元数据的根目录 (默认为 ~/.local/pipx)。
PIPX_BIN_DIR: 定义 pipx 链接应用可执行文件的目录 (默认为 ~/.local/bin)。

如果你修改了这些变量，记得也要更新你的 PATH 环境变量，并可能需要运行 pipx ensurepath 来帮助你设置。

示例 (在你的 .bashrc 或 .zshrc 中设置)：

export PIPX_HOME=/opt/pipx_venvs
export PIPX_BIN_DIR=/opt/pipx_bin
export PATH="$PIPX_BIN_DIR:$PATH" # 确保新的 bin 目录在 PATH 中

修改后请重新加载 shell 配置或重启终端。

3.3 注入额外的包到应用环境中 (pipx inject)

有时，一个通过 pipx 安装的应用可能需要一些可选的依赖或插件才能启用特定功能。你可以使用 pipx inject 命令将额外的包安装到该应用已存在的隔离环境中。

示例：

假设你安装了 black，并且想为它安装 jupyter 插件（注意：这只是一个假设的例子，black 本身可能不需要这样操作，具体看应用文档）。

pipx install black
pipx inject black some-black-plugin another-plugin

查看注入的包：
```
pipx list --include-injected black
```
谨慎使用 inject： inject 的主要目的是为了应用的插件或可选依赖。过度使用 inject 来构建复杂的环境可能会违背 pipx 保持应用隔离和简洁的初衷。如果一个应用需要很多额外的包才能运行，可能它更适合通过 pip 在一个专门的虚拟环境中进行管理 (例如使用 venv 或 conda)。

4. 常用命令总结

命令	描述
`pipx install <pkg>`	安装一个 Python 应用到隔离环境。
`pipx run <pkg> [args...]`	在临时环境中运行一个 Python 应用。
`pipx uninstall <pkg>`	卸载一个应用及其环境。
`pipx uninstall-all`	卸载所有通过 `pipx` 安装的应用。
`pipx list`	列出所有已安装的应用。
`pipx upgrade <pkg>`	升级一个已安装的应用。
`pipx upgrade-all`	升级所有已安装的应用。
`pipx reinstall <pkg>`	重新安装一个应用 (使用与之前相同的 Python 版本)。
`pipx reinstall-all`	重新安装所有应用。
`pipx inject <pkg> [deps...]`	将额外的包注入到已安装应用的环境中。
`pipx ensurepath`	确保 `pipx` 的可执行文件路径 (通常是 `~/.local/bin`) 在你的 PATH 中。
`pipx completions`	为你的 shell 生成自动补全脚本。
`pipx --version`	显示 `pipx` 的版本。
`pipx <command> --help`	显示特定命令的帮助信息。

何时使用 `pipx` vs `pip`?

使用 pipx：
- 当你想要安装和运行一个主要作为命令行工具/应用的 Python 包时 (例如 httpie, black, poetry, ansible, awscli 等)。
- 你希望这些工具全局可用，但又不想它们污染你的系统 Python 或其他项目的环境。
使用 pip (通常在虚拟环境中，如 venv)：
- 当你为一个特定的 Python 项目安装库依赖时 (例如 requests, numpy, django 等)。这些是你会在 Python 代码中 import 的库。
- 这些库是项目的一部分，而不是独立的命令行应用。

希望这个教程能帮助你开始使用 pipx！它是一个非常实用的工具，可以让你的 Python 应用管理更加清爽和高效。

包管理工具uv使用教程

Sun, 11 May 2025 00:00:00 +0000

github地址


- UV常用命令
- pyproject.toml使用
- uv tool 使用

错误解决

-uv sync报错：hint: This usually indicates a problem with the package or the build environment.

-[下载速度慢？使用 export UV_INDEX_URL=https://pypi.tuna.tsinghua.edu.cn/simple 设置镜像源]

uv常用命令

# 初始化一个新的 Python 项目 and 创建toml文件
uv init <project-name>

# 创建虚拟环境
uv venv

# 激活虚拟环境（Unix/macOS）
source .venv/bin/activate
# 激活虚拟环境（Windows）
.venv\Scripts\activate

# 安装依赖
uv pip install <package-name>

# 安装项目依赖（从 pyproject.toml 或 requirements.txt）
uv pip install -r requirements.txt
# 或
uv pip install .

# 升级包
uv pip install --upgrade <package-name>

# 卸载包
uv pip uninstall <package-name>

# 列出已安装的包
uv pip list

# 导出依赖到 requirements.txt
uv pip freeze > requirements.txt

# 运行 Python 脚本或命令
uv run <script.py>
# 或
uv run python <script.py>

# 添加依赖到 pyproject.toml
uv add <package-name>

# 移除依赖从 pyproject.toml
uv remove <package-name>

# 同步项目依赖（确保虚拟环境与 pyproject.toml 一致）
uv sync # 如果只有requirements.txt使用uv sync --requirements requirements.txt

# 查看依赖树
uv tree

# 清理缓存
uv cache clean

# 检查 uv 版本
uv --version

UV 是一个由 Astral (Ruff 的开发者) 开发的、用 Rust 编写的极速 Python 包安装器和解析器。它的目标是成为 pip 和 venv 的直接替代品，提供更快、更友好的用户体验。

教程大纲:

UV 是什么？为什么选择 UV？
安装 UV
核心概念
- 虚拟环境管理
- 包管理 (作为 pip 的替代)
- 依赖解析
- 全局缓存
基本命令详解
- 创建和管理虚拟环境 (uv venv)
- 安装包 (uv pip install)
- 卸载包 (uv pip uninstall)
- 列出已安装的包 (uv pip list)
- 生成依赖文件 (uv pip freeze)
- 从依赖文件安装 (uv pip install -r, uv pip sync)
- 编译依赖 (uv pip compile)
高级用法和特性
- 使用 pyproject.toml
- 临时执行包 (uvx)
- 缓存管理 (uv cache)
与 pip 的主要区别和优势
总结与展望

基础知识

1. UV 是什么？为什么选择 UV？

UV 是什么？ UV 是一个实验性的 Python 包管理工具，旨在提供一个非常快速的、统一的包安装和虚拟环境管理体验。它被设计为 pip, pip-tools (特别是 pip-compile) 和 venv 的替代品。
为什么选择 UV？
- 速度极快: UV 使用 Rust 编写，并在依赖解析和包安装方面进行了大量优化，通常比 pip 快几个数量级，尤其是在复杂的依赖关系或冷缓存启动时。
- 统一体验: 将虚拟环境创建 (venv) 和包安装/管理 (pip) 功能整合到单个命令行工具 uv 中。
- 更好的依赖解析器: UV 内置了一个高性能的依赖解析器，可以更快、更准确地解决复杂的依赖冲突。
- 现代化的设计: 遵循最新的 Python 打包标准 (如 PEP 517, PEP 621)。
- 全局缓存: UV 使用一个共享的全局缓存来存储下载的包和构建的轮子 (wheels)，这使得在不同项目中重用依赖时速度更快，并节省磁盘空间。
- pip-compile 功能内置: uv pip compile 命令提供了类似于 pip-tools 的依赖锁定功能。
- uvx: 类似于 npx (Node.js) 或 pipx run，允许你临时执行来自 PyPI 的包，而无需将其安装到你的项目中或全局环境中。

2. 安装 UV

在linux或者mac中安装你可以通过多种方式安装 UV：

使用 curl (Linux & macOS):

curl -LsSf https://astral.sh/uv/install.sh | sh

使用 pip (不推荐用于全局安装，除非在隔离环境中):
```
pip install uv
```
使用 pipx (推荐，用于将 UV 安装到隔离环境中):
```
pipx install uv
```
如果你没有 pipx, 可以先安装它: pip install pipx

使用 cargo (如果你是 Rust 开发者):
```
cargo install uv
```

在windows中安装

安装教程

从 GitHub Releases 下载预编译的二进制文件。 下载地址

安装完成后，验证安装：

uv --version

注意：如果你发现安装好之后，vscode/cursor中的terminal并没有生效，那么需要完全重启vscode/cursor

3. 核心概念

虚拟环境管理: UV 可以像 python -m venv 或 virtualenv 一样创建和管理虚拟环境。它会将环境创建在 .venv 目录（默认）或你指定的目录。
包管理 (作为 pip 的替代): uv pip 子命令旨在成为 pip 命令的直接替代品。大多数你熟悉的 pip 命令都可以用 uv pip 替代，例如 uv pip install <package>, uv pip uninstall <package>。
依赖解析: UV 的核心优势之一是其快速且健壮的依赖解析器。当你安装包或编译需求文件时，它会分析所有直接和间接的依赖关系，找到一组兼容的版本。
全局缓存: UV 会在用户缓存目录（例如 ~/.cache/uv 或 %LOCALAPPDATA%\uv\cache）中维护一个全局缓存。这包括下载的包索引、sdist、wheel 文件等。这意味着如果你在项目 A 中安装了 requests==2.30.0，在项目 B 中再次安装相同版本的 requests 时，UV 可以直接从缓存中获取，无需重新下载或构建。

4. 基本命令详解

创建和管理虚拟环境 (`uv venv`)

创建虚拟环境: 默认情况下，会在当前目录下创建一个名为 .venv 的虚拟环境。

uv venv

你也可以指定环境名称和 Python解释器：

uv venv myenv --python 3.11 # 使用 python3.11 创建名为 myenv 的环境
uv venv .env -p 3.9 # 使用 python3.9 创建名为 .env 的环境

激活虚拟环境: UV 创建的虚拟环境与标准 venv 模块创建的环境结构相同，激活方式也一样：
- Linux/macOS:
```
source .venv/bin/activate
# 或 source myenv/bin/activate
```
- Windows (CMD):
```
.venv\Scripts\activate.bat
```
- Windows (PowerShell):
```
.venv\Scripts\Activate.ps1
```
激活后，命令行提示符通常会显示虚拟环境的名称。
停用虚拟环境:
```
deactivate
```

安装包 (`uv pip install`)

从 PyPI 安装最新版本: (确保你已激活虚拟环境，或者 UV 会尝试安装到全局环境，除非配置了 UV_SYSTEM_PYTHON=true 来明确允许)
```
uv pip install requests
uv pip install flask sqlalchemy
```

安装特定版本:

uv pip install "requests==2.28.1"
uv pip install "django>=3.2,<4.0"

从 requirements.txt 文件安装:
```
uv pip install -r requirements.txt
```

从本地项目安装 (使用 pyproject.toml 或 setup.py):

uv pip install . # 安装当前目录下的项目
uv pip install -e . # 以可编辑模式安装

从 Git 仓库安装:

uv pip install git+https://github.com/pallets/flask.git

指定索引 URL:

uv pip install --index-url https://my-private-index/simple requests

卸载包 (`uv pip uninstall`)

uv pip uninstall requests
uv pip uninstall requests flask

可以配合 -r requirements.txt 使用，卸载文件中列出的所有包。

列出已安装的包 (`uv pip list`)

uv pip list
uv pip list --format freeze # 输出格式与 requirements.txt 相同
uv pip list --format json # 输出为 JSON 格式

生成依赖文件 (`uv pip freeze`)

这会将当前环境中所有已安装的包及其版本输出到标准输出，通常用于生成 requirements.txt 文件。

uv pip freeze > requirements.txt

从依赖文件安装 (`uv pip install -r`, `uv pip sync`)

uv pip install -r requirements.txt: 安装 requirements.txt 中列出的所有包。如果某些包已安装但版本不匹配，UV 会尝试升级或降级。如果某些包已安装但不在文件中，它们不会被卸载。
uv pip sync requirements.txt: 推荐使用 sync 来精确同步环境。 此命令会确保你的虚拟环境与 requirements.txt 文件中的内容 完全一致。
- 安装文件中列出的、但尚未安装的包。
- 升级或降级已安装的、但版本与文件中不符的包。
- 卸载环境中已安装的、但未在文件中列出的包。 这对于确保环境的纯净和可复现性非常有用。
如果你也使用 pyproject.toml (见下文)，你可以同步项目的依赖：
```
uv pip sync pyproject.toml
# 或 uv pip sync (如果 pyproject.toml 在当前目录)
```

编译依赖 (`uv pip compile`)

类似于 pip-compile (来自 pip-tools)，此命令用于将高层级的依赖需求（例如 requirements.in 或 pyproject.toml）解析并锁定为具体的版本，输出到一个完全固定的依赖文件（例如 requirements.txt）。

从 requirements.in 编译到 requirements.txt: requirements.in (示例):
```
flask
requests>=2.20
```
编译命令:
```
uv pip compile requirements.in -o requirements.txt
```
这会生成一个 requirements.txt 文件，其中包含 Flask、Requests 以及它们所有子依赖的精确版本。

从 pyproject.toml 编译: 如果你的项目使用 pyproject.toml 定义依赖： pyproject.toml (部分示例):

[project]
name = "my-app"
version = "0.1.0"
dependencies = [
 "flask",
 "requests>=2.20",
]

[project.optional-dependencies]
dev = [
 "pytest",
 "black",
]

编译命令:

# 编译核心依赖
uv pip compile pyproject.toml -o requirements.txt

# 编译核心依赖和 'dev' 附加依赖
uv pip compile pyproject.toml --extra dev -o requirements-dev.txt

pyproject.toml使用

# Initialize a new project with pyproject.toml
uv init <project-name>

# Add a dependency to pyproject.toml
uv add <package>

# Remove a dependency from pyproject.toml
uv remove <package>

# Sync dependencies from pyproject.toml to virtual environment
uv sync

# Update dependencies and lockfile
uv lock

# Run a script or command in the project environment
uv run <script-or-command>

# Display dependency tree
uv tree

# Add a development dependency
uv add --dev <package>

# Create or update uv.lock file
uv lock

# Build a source distribution or wheel
uv build

# Publish the project to a package index
uv publish

# Export dependencies to requirements.txt
uv export

# Check or manage Python version
uv python

在 Python 项目中使用 uv 包管理工具时，pyproject.toml 是其核心配置文件，用于定义项目元数据、依赖关系和构建配置。以下是关于如何使用 uv 的 pyproject.toml 文件的详细说明：

基本结构 pyproject.toml 文件基于 TOML 格式，uv 使用它来管理项目的依赖、元数据和构建配置。以下是一个典型的 pyproject.toml 文件结构：

[project]
name = "my-project"
version = "0.1.0"
description = "A sample Python project"
readme = "README.md"
requires-python = ">=3.8"
dependencies = [
 "requests>=2.25.1",
 "pandas>=1.5.0",
]

[tool.uv]
 uv 特定的配置
dev-dependencies = [
 "pytest>=7.0.0",
 "black>=23.0.0",
]

关键字段说明 [project] 部分这是 PEP 621 标准定义的项目元数据部分，uv 使用它来了解项目的基本信息和依赖。

name: 项目名称，必须唯一。
version: 项目版本号，建议遵循语义化版本规范（Semantic Versioning）。
description: 项目简短描述。
readme: 项目 README 文件路径（用于生成项目描述）。
requires-python: 指定支持的 Python 版本（例如 >=3.8）。
dependencies: 项目的生产依赖列表，格式为包名和版本约束。

[tool.uv] 部分这是 uv 专用的配置部分，用于定义 uv 特定的设置。

dev-dependencies: 开发环境依赖（如测试、格式化工具），与生产依赖分开管理。
其他配置（可选）：
- index-url: 指定自定义的 PyPI 源，例如 "https://pypi.company.com/simple".
- extra-index-url: 额外的 PyPI 源。
- constraint: 指定依赖约束文件路径。
- override: 指定依赖覆盖文件路径。

使用 uv 管理 pyproject.toml 以下是如何结合 uv 命令和 pyproject.toml 进行项目管理的常见操作：

初始化项目运行以下命令，uv 会自动创建一个基础的 pyproject.toml 文件：

uv init my-project

这会生成一个包含 [project] 部分的 pyproject.toml，你可以根据需要编辑。

添加依赖

添加生产依赖：
```
uv add requests
```
这会在 pyproject.toml 的 [project] 部分添加 requests 依赖。
添加开发依赖：
```
uv add --dev pytest
```
这会在 [tool.uv] 部分添加 pytest 作为开发依赖。

移除依赖

移除生产依赖：
```
uv remove requests
```
移除开发依赖：
```
uv remove --dev pytest
```

同步依赖运行以下命令，确保虚拟环境中的依赖与 pyproject.toml 一致：

uv sync

这会安装 [project.dependencies] 和 [tool.uv.dev-dependencies] 中的所有依赖。

运行项目使用 uv run 执行脚本或命令，自动使用虚拟环境的依赖：

uv run python main.py

锁定依赖 uv 会生成一个 uv.lock 文件，用于锁定依赖的确切版本，确保可重复构建：

uv lock

uv.lock 是自动生成的，不需要手动编辑。

示例：完整的 pyproject.toml 以下是一个更完整的示例，包含多种配置：

[project]
name = "my-project"
version = "0.2.0"
description = "A Python project managed by uv"
authors = [
 { name = "Your Name", email = "your.email@example.com" }
]
license = "MIT"
requires-python = ">=3.9"
dependencies = [
 "fastapi>=0.95.0",
 "uvicorn>=0.20.0",
]

[tool.uv]
dev-dependencies = [
 "pytest>=7.3.0",
 "ruff>=0.1.0",
 "mypy>=1.0.0",
]
index-url = "https://pypi.org/simple"
extra-index-url = ["https://test.pypi.org/simple"]

[build-system]
requires = ["hatchling"]
build-backend = "hatchling.build"

注意事项

版本约束：依赖版本使用 PEP 440 规范，例如 >=1.0.0,<2.0.0。
虚拟环境：uv 自动在项目目录下的 .venv 创建虚拟环境，运行 uv sync 即可激活。
兼容性：uv 的 pyproject.toml 遵循 PEP 621 标准，与其他工具（如 poetry、pdm）兼容，但 [tool.uv] 是 uv 专有。
锁定文件：uv.lock 确保依赖版本一致，建议将其加入版本控制。
自定义源：如果使用私有 PyPI 源，确保在 [tool.uv] 中正确配置 index-url 或 extra-index-url。

常见问题

如何迁移现有项目到 uv？
1. 确保 pyproject.toml 包含 [project] 部分，列出依赖。
2. 运行 uv lock 生成 uv.lock。
3. 运行 uv sync 安装依赖。
如何处理依赖冲突？ 使用 uv lock --verbose 查看冲突详情，必要时在 [tool.uv] 中添加 constraint 文件。
如何运行特定命令？ 使用 uv run 执行命令，例如 uv run pytest tests/。

更多资源

官方文档：访问 uv 文档获取最新信息。
示例项目：查看 uv 的 GitHub 仓库或官方示例。
如果需要实时搜索最新信息，可使用 uv 的 X 社区或 PyPI 页面。

如果你有具体的 pyproject.toml 配置问题或需要进一步示例，请提供更多细节，我可以为你定制解答！

uv tool的使用方法

# 安装命令行工具到持久化环境
uv tool install <package> # 安装指定包的工具（如 ruff）
uv tool install <package>==<version> # 安装特定版本的工具
uv tool install <package> --with <dep> # 安装工具并附带额外依赖
uv tool install <package> --python <version> # 使用指定 Python 版本安装
uv tool install -e . # 以 editable 模式安装当前目录项目（开发 CLI 工具时常用）
uv tool install -e . --force # 强制重新安装当前目录 editable 项目

# 在临时环境中运行工具（别名 uvx）
uvx <command> # 运行工具（如 uvx pycowsay 'hello'）
uvx <command>@<version> # 运行特定版本的工具
uvx --from <package> <command> # 指定提供命令的包（如 uvx --from httpie http）
uvx --python <version> <command> # 使用指定 Python 版本运行

# 升级已安装的工具
uv tool upgrade <package> # 升级工具到最新版本（尊重版本约束）

# 列出已安装的工具
uv tool list # 显示所有通过 uv tool install 安装的工具

# 卸载工具
uv tool uninstall <package> # 移除指定工具及其环境

# 更新 shell 配置以确保工具可执行文件在 PATH 中
uv tool update-shell # 添加 ~/.local/bin 到 PATH

以下是关于 Python 包管理工具 uv 中 tool 功能的详细使用教程，基于官方文档和相关资料整理，涵盖安装、运行、管理工具等核心操作，并提供示例以便于理解。

什么是 uv 的 tool 功能？

uv 的 tool 功能允许用户安装和运行 Python 包提供的命令行工具（类似 pipx），并在隔离的环境中执行这些工具。它特别适合需要快速运行 CLI 工具（如 ruff、pytest 或 huggingface-cli）的场景。uv tool 提供了以下优势：

隔离性：工具运行在独立的虚拟环境中，避免与项目依赖冲突。
高效性：利用 uv 的高速缓存和 Rust 实现，安装和运行工具极快。
兼容性：支持 pip 生态系统，易于迁移和使用。

uv tool 主要命令包括：

uv tool install：安装工具及其依赖。
uv tool run（别名 uvx）：在临时环境中运行工具。
uv tool upgrade：升级已安装的工具。
uv tool list：列出已安装的工具。
uv tool uninstall：卸载工具。

使用 uv tool 的教程

以下是 uv tool 的核心功能和使用步骤，包含具体命令和示例。

安装命令行工具 (uv tool install)

使用 uv tool install 将一个 Python 包提供的命令行工具安装到持久化环境中，工具的可执行文件会自动添加到 PATH 中。

语法：

uv tool install <package> [options]

常用选项：

--with <package>：安装额外的依赖包。
--python <version>：指定 Python 版本。
--force：强制重新安装。
--from <package>：指定工具来源包（当包名和工具名不同时）。
-e, --editable：以可编辑模式安装本地项目，开发 CLI 工具时无需重复安装即可生效代码改动。

示例 1：安装 ruff 工具 ruff 是一个快速的 Python 代码检查工具。

uv tool install ruff

安装后，运行以下命令验证：
```
ruff --version
```
输出示例：
```
ruff 0.5.4
```

示例 2：安装 huggingface-cli 工具 huggingface_hub 包提供了 huggingface-cli 工具，用于与 Hugging Face 仓库交互。

uv tool install huggingface_hub

运行工具：
```
huggingface-cli --version
```

示例 3：安装特定版本的工具 安装特定版本的 ruff：

uv tool install 'ruff==0.5.0'

示例 4：安装带有额外依赖的工具 安装 mkdocs 并附带 mkdocs-material 主题：

uv tool install mkdocs --with mkdocs-material

示例 5：以 editable 模式安装本地项目（开发 CLI 工具） 如果你正在开发一个包含 [project.scripts] 入口点的 Python 包，可以用 editable 模式将其安装为命令行工具：

uv tool install -e .

这样安装后，修改源码无需重新安装即可生效。
配合 --force 可在源码结构或入口点变更时强制刷新：
```
uv tool install --editable --force .
```

注意：

安装的工具可执行文件默认位于 ~/.local/bin/（Linux/macOS）或 %USERPROFILE%\.local\bin（Windows）。确保该路径在 PATH 中。
如果工具未自动添加到 PATH，运行以下命令更新 shell 配置：
```
uv tool update-shell
```

运行工具 (uv tool run / uvx)

使用 uv tool run（或其别名 uvx）可以在临时虚拟环境中运行工具，无需持久化安装。适合一次性使用或测试。

语法：

uvx <command> [args]
 或
uv tool run <command> [args]

常用选项：

--from <package>：指定提供命令的包（当包名和命令名不同时）。
--python <version>：指定 Python 版本。
@<version>：运行特定版本的工具。

示例 1：运行 pycowsay 运行 pycowsay 工具生成 ASCII 艺术：

uvx pycowsay 'hello world!'

输出示例：

 ------------
< hello world! >
 ------------
 ^__^
 (oo)\_______
 (__)\ )\/\
 ||----w |
 || ||

示例 2：运行特定包的工具 httpie 包提供 http 命令：

uvx --from httpie http https://example.com

示例 3：运行特定版本的工具 运行 ruff 的 0.3.0 版本：

uvx ruff@0.3.0 check

示例 4：指定 Python 版本 使用 Python 3.12 运行 ruff：

uvx --python 3.12 ruff --version

注意：

uvx 运行的工具在命令执行后，临时环境会被销毁。
如果工具需要频繁使用，建议用 uv tool install 安装到持久化环境。

升级工具 (uv tool upgrade)

升级已安装的工具到最新版本，尊重安装时的版本约束。

语法：

uv tool upgrade <package>

示例：升级 ruff

uv tool upgrade ruff

如果安装时指定了版本范围（如 ruff>=0.3,<0.4），升级将保持在该范围内。
要更改版本约束，重新运行 uv tool install：
```
uv tool install 'ruff>=0.4'
```

列出已安装工具 (uv tool list)

查看所有通过 uv tool install 安装的工具。

语法：

uv tool list

示例：

uv tool list

输出示例：

ruff (0.5.4)
huggingface-cli (0.23.0)

卸载工具 (uv tool uninstall)

移除已安装的工具及其环境。

语法：

uv tool uninstall <package>

示例：卸载 ruff

uv tool uninstall ruff

管理工具依赖

uv tool 安装的工具不会将其模块暴露给当前 Python 环境，以避免冲突。例如，安装 ruff 后，以下命令会失败：

python -c "import ruff"

这是设计使然，确保工具的依赖与项目隔离。

如果需要将工具的模块用于项目，改用 uv add 或 uv pip install 将包安装到项目环境中：

uv add ruff

高级用法：结合 pyproject.toml

对于项目管理，uv 支持在 pyproject.toml 中定义工具依赖组。例如，添加 pytest 到开发依赖组：

编辑 pyproject.toml：

[project]
name = "my-project"
version = "0.1.0"
dependencies = ["fastapi"]

[dependency-groups]
dev = ["pytest>=8.3.4"]
lint = ["ruff>=0.5.4"]

安装依赖：

uv sync --group dev

运行 pytest：
```
uv run pytest
```

运行 lint 工具：

uv run ruff check

常见问题与解决方案

问题：工具命令未找到。
- 解决：确保 ~/.local/bin 在 PATH 中，运行 uv tool update-shell 或手动添加：
```
export PATH="$HOME/.local/bin:$PATH"
```
问题：工具运行时依赖冲突。
- 解决：使用 uvx 在临时环境中运行，或检查 pyproject.toml 中的依赖版本。
问题：需要特定 Python 版本。
- 解决：使用 uv python install 安装所需版本：
```
uv python install 3.11
uvx --python 3.11 <command>
```

最佳实践

优先使用 uvx 进行测试：
- 对于不常使用的工具，使用 uvx 避免占用磁盘空间。
- 示例：uvx black --version 检查 black 版本。
持久化常用工具：
- 使用 uv tool install 安装频繁使用的工具（如 ruff、pytest），并确保 PATH 配置正确。
结合 CI/CD：
- 在 CI/CD 管道中，使用 uv tool install 安装工具，确保一致性。例如：
```
uv tool install ruff
ruff check .
```
保持版本一致：
- 使用 uv.lock 和 pyproject.toml 锁定工具版本，确保团队成员和生产环境使用相同版本。
定期清理：
- 使用 uv tool list 检查已安装工具，uv tool uninstall 移除不再需要的工具。

示例工作流：设置开发环境

假设你要为一个 FastAPI 项目设置 ruff（代码检查）和 pytest（测试）工具：

初始化项目：
```
uv init my-project
cd my-project
```
添加项目依赖：
```
uv add fastapi
```

添加开发工具：

uv add --group dev pytest
uv add --group lint ruff

安装工具：

uv tool install ruff
uv tool install pytest

运行检查和测试：
```
ruff check .
uv run pytest
```
检查工具：
```
uv tool list
```

局限性

不完全兼容 pip：某些 pip 功能（如 .egg 依赖、特定 Git 安装）暂不支持。查看 pip 兼容性指南获取详情。
早期开发阶段：部分功能可能不稳定，建议关注 GitHub Issues 获取最新更新。
工具隔离：uv tool install 的模块不可导入到项目中，需单独安装依赖。

参考资料

官方文档：https://docs.astral.sh/uv/guides/tools/
GitHub 仓库：https://github.com/astral-sh/uv
UV 工具介绍：https://www.saaspegasus.com/guides/uv-python-package-manager/
示例教程：https://realpython.com/python-uv/

与 Jupyter Notebook / JupyterLab 集成

4.2 设置步骤

# 4.2.1 创建并激活项目的 uv 虚拟环境 
uv venv .venv && source .venv/bin/activate

# 4.2.2 在 uv 环境中安装 Jupyter 和 ipykernel
uv pip install jupyterlab ipykernel (或 notebook ipykernel)
#建议将这些作为开发依赖添加到 pyproject.toml

# 4.2.3 (推荐) 将 uv 环境注册为 Jupyter 内核 (Kernel) 
uv run python -m ipykernel install --user --name=my-project-venv --display-name="Python (my-project-venv)"


# 4.2.4 启动 JupyterLab 或 Jupyter Notebook 
从已激活 uv 环境的终端启动：uv run jupyter lab 或 uv run jupyter notebook
或者全局安装的 Jupyter 自动检测到注册的内核

# 4.2.5 在 Jupyter 中选择和使用 uv 环境的内核

4.3 管理项目依赖

在 Notebook 中通过 !uv pip install <new_package> (不推荐长期做法)

正确做法：在终端中激活 uv 环境，使用 uv pip install，然后重启 Jupyter 内核

使用 pyproject.toml 和 uv pip compile / uv pip sync 管理 Jupyter 项目的依赖

4.4 移除 Jupyter 内核 (如果已注册)

jupyter kernelspec list

jupyter kernelspec uninstall my-project-venv

5. 高级用法和特性

使用 `pyproject.toml`

UV 对 PEP 621 (pyproject.toml 中的 [project] 表) 有良好支持。

uv pip install .: 会读取 pyproject.toml 中的 dependencies。
uv pip install .[extra]: 会安装核心依赖和指定的 optional-dependencies。
uv pip sync pyproject.toml: 会同步环境以匹配 pyproject.toml 中定义的核心依赖。
uv pip sync pyproject.toml --extra dev: 同步核心依赖和 dev 附加依赖。
uv pip compile pyproject.toml: 将 pyproject.toml 中的依赖编译成锁文件。

临时执行包 (`uvx`)

uvx 允许你执行来自 PyPI 的命令行工具，而无需将其永久安装到你的项目虚拟环境或全局 Python 环境中。UV 会在后台创建一个临时的隔离环境来运行该工具。

这对于代码格式化器、linter 或一次性脚本非常有用。

uvx black . # 临时下载 black 并用它格式化当前目录代码
uvx cowsay "Hello UV"
uvx python -m http.server # 临时运行一个 http 服务器

uvx 会缓存下载的包，所以后续执行会更快。

缓存管理 (`uv cache`)

查看缓存目录:
```
uv cache dir
```
清理缓存:
```
uv cache clean
# 或者 uv cache prune (更推荐，会保留最近使用的条目)
```
清理缓存可以释放磁盘空间，但下次安装包时可能需要重新下载。

6. 与 pip 的主要区别和优势

特性	UV	pip + venv + pip-tools
核心语言	Rust	Python
速度	极快 (通常快几个数量级)	较慢
工具集	单一工具 `uv` (包含 venv, pip, compile)	多个工具 (`python -m venv`, `pip`, `pip-compile`)
依赖解析	内置高性能解析器	依赖外部解析器 (有时较慢或不够健壮)
缓存	智能全局缓存	每个虚拟环境或用户级缓存 (pip >= 20.1)
`sync`	`uv pip sync` 精确同步环境	无直接对应命令 (需手动组合)
`uvx`	`uvx <cmd>` 临时执行包	`pipx run <cmd>` (需要额外安装 `pipx`)
`compile`	`uv pip compile` 内置依赖锁定	`pip-compile` (需要额外安装 `pip-tools`)
错误信息	通常更清晰	有时冗长

主要优势总结:

性能: 最显著的优势，尤其在大型项目或 CI/CD 环境中。
易用性: 单个工具简化了工作流程。
强大的依赖管理: 内置的编译和同步功能使得依赖管理更稳健。

7. 总结与展望

UV 是一个非常有前途的 Python 打包工具，它通过 Rust 实现带来了显著的性能提升和现代化的用户体验。它旨在简化 Python 开发者的日常工作，从创建环境到安装、管理和锁定依赖。

虽然 UV 仍在积极开发中（截至2025年初），但它已经足够稳定和强大，可以在许多项目中使用，特别是对于那些对性能有较高要求的场景。

建议:

尝试一下！ 特别是如果你对当前 pip 和 venv 的速度或工作流程感到不满。
关注 Astral 的官方博客和 UV 的 GitHub 仓库 (https://github.com/astral-sh/uv) 以获取最新的更新和功能。
可以考虑在你的项目中逐步引入 UV，例如先用它来创建虚拟环境和安装包，然后再尝试 uv pip compile 和 uv pip sync。

错误解决

problem_with_the_package_or_the_build_environment

我在使用uv sync时候，当安装到obspy时遇到报错，具有报错信息如下

 hint: This usually indicates a problem with the package or the build environment.
 help: `obspy` (v1.4.2) was included because `dataanalysismodels` (v0.1.0) depends on `obspy`

进一步使用 *uv pip install obspy –no-cache-dir * 命令单独安装obspy的时候报错如下

 check.warn(importable)
 error: command 'cc' failed: No such file or directory

 hint: This usually indicates a problem with the package or the build environment.

通过询问ai，这里的原因是，我缺失C的编译环境，因此使用如下命令安装C的编译环境

apt-get update
apt-get install -y build-essential gcc g++ libffi-dev python3-dev

但是报错 (使用 dpkg –configure -a 解决)

(dataAnalysisModels) root@ce4322c051c6:/codes/dataAnalysisModels# apt-get install -y build-essential gcc g++ libffi-dev python3-dev
E: dpkg was interrupted, you must manually run 'dpkg --configure -a' to correct the problem.

于是使用dpkg –configure -a 命令解决

setuptools-打包python项目为egg / 安装库函数

Mon, 28 Apr 2025 16:41:54 +0800

这是一个使用 setuptools 将 Python 项目打包为 .egg 文件的详细教程，包含源代码示例。

请注意： .egg 格式是较旧的 Python 分发格式。目前更推荐使用 .whl (Wheel) 格式，它在安装速度和兼容性方面有优势。然而，如果你确实需要创建 .egg 文件（例如，为了兼容旧系统或特定工具），可以按照以下步骤进行。

简易教程1：使用 setuptools 打包 Python 项目为 Egg

1. 项目结构

首先，你需要一个标准的 Python 项目结构。一个典型的结构如下所示：

my_package/
├── my_package/
│ ├── __init__.py
│ └── module1.py
├── setup.py
├── README.md
└── LICENSE

my_package/: 这是你的实际 Python 包目录，其中包含你的模块和代码。
my_package/__init__.py: 这个文件使 my_package 成为一个 Python 包。它可以是空的，也可以包含包的初始化代码。
my_package/module1.py: 这是一个示例模块文件，包含你的项目代码。
setup.py: 这是 setuptools 的配置文件，用于描述你的项目以及如何打包。
README.md: 项目的说明文件（推荐）。
LICENSE: 项目的许可证文件（推荐）。

2. 创建示例项目代码

在 my_package/module1.py 中添加一些示例代码：

# my_package/module1.py

def greet(name):
 """
 一个简单的问候函数。
 """
 return f"Hello, {name}!"

def farewell(name):
 """
 一个简单的告别函数。
 """
 return f"Goodbye, {name}!"

在 my_package/__init__.py 中，你可以选择导入 module1 中的函数，以便用户可以直接从 my_package 导入它们：

# my_package/__init__.py

from .module1 import greet, farewell

__version__ = "0.1.0" # 添加一个版本号

3. 创建 setup.py 文件

setup.py 文件是使用 setuptools 打包项目的核心。它包含了项目的元数据和打包指令。

# setup.py

from setuptools import setup, find_packages

setup(
 name='my_awesome_package', # 包的名称，用户将使用此名称安装
 version='0.1.0', # 包的版本号
 description='A simple example package to demonstrate egg packaging', # 包的简短描述
 long_description=open('README.md').read(), # 详细描述，通常来自 README 文件
 long_description_content_type='text/markdown', # 详细描述的格式
 author='Your Name', # 作者姓名
 author_email='your.email@example.com', # 作者邮箱
 url='https://github.com/yourusername/my_awesome_package', # 项目主页或其他 URL
 packages=find_packages(), # 自动查找项目中的所有包
 classifiers=[ # 分类器，帮助用户在 PyPI 上找到你的包
 'Programming Language :: Python :: 3',
 'License :: OSI Approved :: MIT License',
 'Operating System :: OS Independent',
 ],
 python_requires='>=3.6', # 项目所需的最低 Python 版本
 install_requires=[ # 项目依赖的第三方库
 # 例如: 'requests>=2.20.0',
 ],
 # 如果你的包包含非 Python 文件 (如数据文件), 可以使用 package_data 或 data_files
 # package_data={
 # 'my_package': ['data/*.txt'],
 # },
 # data_files=[
 # ('my_data', ['data/my_data.csv']),
 # ],

 # 定义命令行脚本 (可选)
 # entry_points={
 # 'console_scripts': [
 # 'my_script = my_package.module1:greet', # 这里的 greet 是一个可执行函数
 # ],
 # },

 # 设置为 True 以便生成 egg 文件
 zip_safe=True,
)

setup() 函数参数说明：

name: 你的包的名称。这是用户在安装时使用的名称（例如 pip install my_awesome_package）。
version: 包的版本号。遵循 Semantic Versioning 是一个好习惯。
description: 包的简短描述。
long_description: 包的详细描述，通常从 README 文件中读取。
long_description_content_type: 详细描述的格式，例如 'text/markdown'。
author 和 author_email: 作者的信息。
url: 项目的主页或代码仓库地址。
packages: 一个列表，列出项目包含的所有 Python 包。find_packages() 函数会自动查找当前目录下的所有包（包含 __init__.py 的目录）。
classifiers: 一个列表，包含描述你的项目的分类器。这些分类器有助于用户在 PyPI (Python Package Index) 上搜索和过滤包。你可以在 PyPI Classifiers 找到完整的列表。
python_requires: 指定项目兼容的 Python 版本范围。
install_requires: 一个列表，列出项目运行时依赖的第三方库。setuptools 会在安装你的包时自动安装这些依赖。
package_data: 用于包含包内部的非 Python 文件，例如数据文件、模板等。键是包名，值是文件路径模式的列表。
data_files: 用于安装不在包内部的文件到指定位置。这在打包可执行脚本或配置文件时很有用。它是一个包含 (destination, files) 元组的列表。
entry_points: 用于定义控制台脚本或其他入口点。这允许你在安装包后直接从命令行运行某个函数。
zip_safe: 如果设置为 True (默认值)，setuptools 会尝试将包打包成一个 ZIP 文件 (即 .egg)。如果你的包需要在安装后从 ZIP 文件中导入模块，并且你没有使用 pkg_resources.resource_filename() 等方法访问包内的文件，通常可以设置为 True。如果你的包需要访问包内的非 Python 文件或有特定的加载需求，可能需要设置为 False，这样包会以目录的形式安装。

4. 生成 Egg 文件

在包含 setup.py 文件的项目根目录下，打开终端或命令行，运行以下命令：

python setup.py bdist_egg

执行此命令后，setuptools 会开始构建过程。成功后，你会在项目根目录下找到一个名为 dist/ 的目录。在该目录中，你会找到生成的 .egg 文件，其名称类似于 my_awesome_package-0.1.0-py3.x.egg (其中 py3.x 表示 Python 版本)。

5. 安装和使用 Egg 文件

你可以使用 easy_install 工具来安装 .egg 文件（easy_install 是 setuptools 自带的安装工具）：

easy_install dist/my_awesome_package-0.1.0-py3.x.egg

或者，你也可以直接将 .egg 文件放置在 Python 的 sys.path 中，Python 就可以直接从中导入模块。

安装后，你就可以像安装其他 Python 包一样导入和使用你的模块了：

# 在 Python 交互式环境中或另一个脚本中
from my_package import greet, farewell

print(greet("World"))
print(farewell("User"))

注意事项和 Egg 的局限性：

兼容性问题： Egg 文件可能在不同的操作系统、Python 版本或架构上存在兼容性问题，尤其当你的项目包含编译后的扩展模块时。
安装复杂性： 相比 Wheel，Egg 的安装通常涉及更多的运行时解压和处理，可能导致安装速度较慢。
不推荐用于新项目： 如前所述，对于新的 Python 项目，强烈建议使用 Wheel 格式进行分发。Wheel 解决了 Egg 的许多缺点，提供了更好的兼容性、更快的安装速度和更简单的结构。
zip_safe=True 的影响： 当 zip_safe 为 True 时，包会被打包到 ZIP 文件中。如果你的代码需要通过文件路径访问包内部的资源（而不是使用 pkg_resources 或 importlib.resources），可能会出现问题。设置为 False 会将包安装为目录，避免这个问题。

6. 如果不打包egg文件也可以直接安装

如果第3步做好了，实际上就已经可以直接安装，在setup.py的同级目录下运行pip install .

总结

通过创建 setup.py 文件并使用 python setup.py bdist_egg 命令，你可以使用 setuptools 将你的 Python 项目打包成 .egg 文件。虽然 Egg 格式在过去很常用，但现在 Wheel 格式已成为首选。在开发新的 Python 包时，优先考虑使用 Wheel 进行分发。如果你需要为旧系统或特定需求创建 Egg 文件，本教程提供了详细的步骤和示例代码。

PyInstaller使用教程

Sun, 27 Apr 2025 10:34:51 +0800

# 将 Python 脚本打包为单个可执行文件
pyinstaller -F script.py

# 打包为目录（包含所有依赖文件）
pyinstaller -D script.py

# 指定输出目录
pyinstaller -F -o output_dir script.py

# 添加图标
pyinstaller -F -i icon.ico script.py

# 隐藏控制台窗口（适用于 GUI 程序）
pyinstaller -F -w script.py

# 添加数据文件
pyinstaller -F --add-data "file.txt;." script.py

# 添加整个目录
pyinstaller -F --add-data "folder;folder" script.py

# 清理缓存和临时文件
pyinstaller --clean script.py

# 指定程序名称
pyinstaller -F -n app_name script.py

# 调试模式（显示更多日志）
pyinstaller -F --debug all script.py

参数说明

-F, --onefile
# 打包为单个可执行文件
# 说明：将 Python 脚本及其所有依赖打包成一个独立的可执行文件。生成的单一文件包含所有库和资源，运行时会解压到临时目录。适合分发简单的应用程序，但启动速度稍慢，且文件体积较大。

-D, --onedir
# 打包为目录，包含可执行文件和依赖
# 说明：将脚本打包为一个目录，包含一个主可执行文件和所有依赖（如动态链接库、资源文件）。相比 --onefile，启动速度更快，文件管理更透明，但分发时需要整个目录。

-o PATH, --out PATH
# 指定输出目录
# 说明：设置 PyInstaller 生成的构建文件和最终输出的目录（包括 dist 和 build 文件夹）。默认情况下，输出在当前工作目录下，PATH 为自定义路径（如 -o ./my_output）。

-i ICON_FILE, --icon ICON_FILE
# 为 Windows 可执行文件添加图标
# 说明：为 Windows 平台的可执行文件指定自定义图标，ICON_FILE 通常为 .ico 文件路径（如 -i my_icon.ico）。仅适用于 Windows，其他平台忽略此选项。

-w, --windowed, --noconsole
# 隐藏控制台窗口，适合 GUI 应用
# 说明：运行程序时不显示命令行窗口，适用于基于 GUI 的应用程序（如 Tkinter、PyQt）。在 Windows 上，生成的是“窗口化”程序；在 macOS 上，生成 .app 包。注意：使用此选项后，程序的控制台输出将不可见。

--add-data "SOURCE;DEST"
# 添加额外的数据文件或目录，格式为 源路径;目标路径
# 说明：将非 Python 文件（如图片、配置文件、数据文件）包含到打包结果中。SOURCE 是文件或目录的路径，DEST 是相对打包目录的目标路径。例如，--add-data "data.txt;." 将 data.txt 放在打包根目录。Windows 用分号 ; 分隔路径，Linux/macOS 用冒号 :（如 --add-data "data.txt:."）。

--clean
# 清理 PyInstaller 的缓存
# 说明：删除 PyInstaller 在构建过程中生成的临时文件和缓存（如 build 文件夹中的缓存）。在遇到打包问题或需要全新构建时使用，有助于避免旧文件干扰。

-n NAME, --name NAME
# 指定生成的可执行文件名
# 说明：设置生成的可执行文件或目录的名称，覆盖默认的脚本文件名。例如，-n my_app 会生成名为 my_app.exe（Windows）或 my_app（Linux/macOS）的文件或目录。

--debug [all|imports|bootloader|noarchive]
# 启用调试模式，查看详细日志
# 说明：启用调试模式以输出详细日志，帮助诊断打包问题。可选值包括：
# - all：输出所有调试信息。
# - imports：显示模块导入过程。
# - bootloader：显示启动加载器的调试信息。
# - noarchive：不将依赖打包为归档，保留解包状态便于检查。
# 例如，--debug all 会输出最详细的日志。


补充说明
参数格式：短选项（如 -F）和长选项（如 --onefile）功能相同，短选项更简洁，长选项更具可读性。
平台差异：某些选项（如 -i 和 -w）主要针对 Windows，Linux/macOS 可能有不同表现。例如，-w 在 macOS 上会生成 .app 包。
路径分隔符：--add-data 的路径分隔符在 Windows 为 ;（如 file.txt;.），在 Linux/macOS 为 :（如 file.txt:.）。
常见组合：例如，pyinstaller -F -w -i icon.ico -n my_app script.py 会生成一个无控制台、带自定义图标、名为 my_app 的单一可执行文件。

一些问题的提醒

`打包时候指定了附加文件，但是打包之后附加文件是放在了__internal文件夹里面的`

我的解决方法是：

使用python代码打包，然后打包好了之后在把文件移动到和exe一个目录

`开发的时候引用脚本没有任何问题，但是打包的时候就出错？`

我的解决方法是：

最好以程序的入口文件位置作为所有脚本的位置
最好使用相对路径：我使用的是 Root_dir = os.path.dirname(os.path.realpath(sys.argv[0])) 作为我所有函数识别的根路径

其他打包工具

cx_Freeze：老牌打包工具，稳定可靠
Auto-py-to-exe：PyInstaller的GUI版本，适合新手使用
Py2exe：仅支持Windows平台的经典工具
PyStand：非常容易快捷的打包方式，只需要把源码和环境拖入制定文件夹就可以

2. 使用PyInstaller进行打包简单使用

pip install pyinstaller

# 最简单的打包
pyinstaller your_script.py

这将生成一个dist文件夹，其中包含可执行文件及其依赖。

也可以使用pyi-makespec命令生成一个.spec文件，然后在.spec文件中进行配置，最后使用pyinstaller命令进行打包。例如：
pyi-makespec your_script.py
然后在生成的.spec文件中进行配置

常用参数说明

PyInstaller提供了多个有用的参数：

基本命令格式:

pyinstaller [options] script.py

基础参数:

-F, --onefile # 打包成一个单独的可执行文件
-D, --onedir # 打包成一个文件夹(默认选项)
-n NAME # 指定生成的可执行文件名
-w, --windowed # Windows系统下不显示命令行窗口
-c, --console # 显示命令行窗口(默认)
--noconfirm # 跳过确认提示,直接覆盖现有文件

路径和文件相关:

--distpath DIR # 指定打包后的输出路径
--workpath DIR # 指定工作目录路径
--specpath DIR # 指定spec文件的生成路径
-p DIR # 添加Python路径(可多次使用)
--add-data # 添加额外的数据文件 
 # 格式: source:dest (Windows用;分隔,Linux用:分隔)
--add-binary # 添加额外的二进制文件

打包控制:

--hidden-import # 添加隐式导入的模块
--additional-hooks-dir # 指定额外的hooks目录
--runtime-hook # 指定运行时hook脚本
--exclude-module # 排除指定模块
--clean # 清理打包前的临时文件

常见实例:

最简单的单文件打包(不需确认):

pyinstaller --noconfirm -F main.py

打包成单文件且不显示控制台:

pyinstaller --noconfirm -F -w main.py

包含数据文件的打包:

# Windows
pyinstaller --noconfirm -F --add-data "resources;resources" main.py

# Linux/MacOS
pyinstaller --noconfirm -F --add-data "resources:resources" main.py

完整的生产环境打包示例:

pyinstaller --noconfirm --onefile --windowed --icon "app.ico" ^
 --hidden-import "PIL" ^
 --add-data "resources;resources" ^
 --add-data "config.yml;." ^
 --name "MyApp" ^
 main.py

配置文件说明

此外，.spec这个文件提供了可以手动写隐式导入配置的功能，在配置文件中的hiddenimports中写入，然后允许pyinstaller手动选择相关.spec文件，后面不用再接其他配置

pyinstaller -F 哔哩.spec

下面是我用于打包gradio项目的gradio源码和一个配置文件的示例，

# gradio_app.py 
import gradio as gr


def greet(name):
 return "Hello " + name + "!!"


demo = gr.Interface(fn=greet, inputs="text", outputs="text")

if __name__ == "__main__":
 demo.launch()

配置文件

生成方式：

 pyi-makespec --collect-all aiofiles --collect-all annotated_types --collect-all anyio --collect-all certifi --collect-all charset_normalizer --collect-all click --collect-all colorama --collect-all dateutil --collect-all fastapi --collect-all ffmpy --collect-all filelock --collect-all fsspec --collect-all gradio --collect-all gradio_client --collect-all groovy --collect-all h11 --collect-all httpcore --collect-all httpx --collect-all huggingface_hub --collect-all idna --collect-all jinja2 --collect-all lxml --collect-all markdown_it --collect-all markupsafe --collect-all mdurl --collect-all multipart --collect-all numpy --collect-all opencc --collect-all orjson --collect-all packaging --collect-all pandas --collect-all pillow --collect-all pip --collect-all pydantic --collect-all pydantic_core --collect-all pydub --collect-all pygments --collect-all python_multipart --collect-all pytz --collect-all requests --collect-all rich --collect-all ruff --collect-all safehttpx --collect-all semantic_version --collect-all setuptools --collect-all shellingham --collect-all sniffio --collect-all starlette --collect-all tomlkit --collect-all tqdm --collect-all typer --collect-all tzdata --collect-all urllib3 --collect-all uvicorn --collect-all websockets --collect-all wheel gradio_app.py

下面是生成得到的配置文件

# gradio_app.spec
# -*- mode: python ; coding: utf-8 -*-
from PyInstaller.utils.hooks import collect_all

datas = []
binaries = []
hiddenimports = []
tmp_ret = collect_all('aiofiles')
datas += tmp_ret[0]; binaries += tmp_ret[1]; hiddenimports += tmp_ret[2]
tmp_ret = collect_all('annotated_types')
datas += tmp_ret[0]; binaries += tmp_ret[1]; hiddenimports += tmp_ret[2]
tmp_ret = collect_all('anyio')
datas += tmp_ret[0]; binaries += tmp_ret[1]; hiddenimports += tmp_ret[2]
tmp_ret = collect_all('certifi')
datas += tmp_ret[0]; binaries += tmp_ret[1]; hiddenimports += tmp_ret[2]
tmp_ret = collect_all('charset_normalizer')
datas += tmp_ret[0]; binaries += tmp_ret[1]; hiddenimports += tmp_ret[2]
tmp_ret = collect_all('click')
datas += tmp_ret[0]; binaries += tmp_ret[1]; hiddenimports += tmp_ret[2]
tmp_ret = collect_all('colorama')
datas += tmp_ret[0]; binaries += tmp_ret[1]; hiddenimports += tmp_ret[2]
tmp_ret = collect_all('dateutil')
datas += tmp_ret[0]; binaries += tmp_ret[1]; hiddenimports += tmp_ret[2]
tmp_ret = collect_all('fastapi')
datas += tmp_ret[0]; binaries += tmp_ret[1]; hiddenimports += tmp_ret[2]
tmp_ret = collect_all('ffmpy')
datas += tmp_ret[0]; binaries += tmp_ret[1]; hiddenimports += tmp_ret[2]
tmp_ret = collect_all('filelock')
datas += tmp_ret[0]; binaries += tmp_ret[1]; hiddenimports += tmp_ret[2]
tmp_ret = collect_all('fsspec')
datas += tmp_ret[0]; binaries += tmp_ret[1]; hiddenimports += tmp_ret[2]
tmp_ret = collect_all('gradio')
datas += tmp_ret[0]; binaries += tmp_ret[1]; hiddenimports += tmp_ret[2]
tmp_ret = collect_all('gradio_client')
datas += tmp_ret[0]; binaries += tmp_ret[1]; hiddenimports += tmp_ret[2]
tmp_ret = collect_all('groovy')
datas += tmp_ret[0]; binaries += tmp_ret[1]; hiddenimports += tmp_ret[2]
tmp_ret = collect_all('h11')
datas += tmp_ret[0]; binaries += tmp_ret[1]; hiddenimports += tmp_ret[2]
tmp_ret = collect_all('httpcore')
datas += tmp_ret[0]; binaries += tmp_ret[1]; hiddenimports += tmp_ret[2]
tmp_ret = collect_all('httpx')
datas += tmp_ret[0]; binaries += tmp_ret[1]; hiddenimports += tmp_ret[2]
tmp_ret = collect_all('huggingface_hub')
datas += tmp_ret[0]; binaries += tmp_ret[1]; hiddenimports += tmp_ret[2]
tmp_ret = collect_all('idna')
datas += tmp_ret[0]; binaries += tmp_ret[1]; hiddenimports += tmp_ret[2]
tmp_ret = collect_all('jinja2')
datas += tmp_ret[0]; binaries += tmp_ret[1]; hiddenimports += tmp_ret[2]
tmp_ret = collect_all('lxml')
datas += tmp_ret[0]; binaries += tmp_ret[1]; hiddenimports += tmp_ret[2]
tmp_ret = collect_all('markdown_it')
datas += tmp_ret[0]; binaries += tmp_ret[1]; hiddenimports += tmp_ret[2]
tmp_ret = collect_all('markupsafe')
datas += tmp_ret[0]; binaries += tmp_ret[1]; hiddenimports += tmp_ret[2]
tmp_ret = collect_all('mdurl')
datas += tmp_ret[0]; binaries += tmp_ret[1]; hiddenimports += tmp_ret[2]
tmp_ret = collect_all('multipart')
datas += tmp_ret[0]; binaries += tmp_ret[1]; hiddenimports += tmp_ret[2]
tmp_ret = collect_all('numpy')
datas += tmp_ret[0]; binaries += tmp_ret[1]; hiddenimports += tmp_ret[2]
tmp_ret = collect_all('opencc')
datas += tmp_ret[0]; binaries += tmp_ret[1]; hiddenimports += tmp_ret[2]
tmp_ret = collect_all('orjson')
datas += tmp_ret[0]; binaries += tmp_ret[1]; hiddenimports += tmp_ret[2]
tmp_ret = collect_all('packaging')
datas += tmp_ret[0]; binaries += tmp_ret[1]; hiddenimports += tmp_ret[2]
tmp_ret = collect_all('pandas')
datas += tmp_ret[0]; binaries += tmp_ret[1]; hiddenimports += tmp_ret[2]
tmp_ret = collect_all('pillow')
datas += tmp_ret[0]; binaries += tmp_ret[1]; hiddenimports += tmp_ret[2]
tmp_ret = collect_all('pip')
datas += tmp_ret[0]; binaries += tmp_ret[1]; hiddenimports += tmp_ret[2]
tmp_ret = collect_all('pydantic')
datas += tmp_ret[0]; binaries += tmp_ret[1]; hiddenimports += tmp_ret[2]
tmp_ret = collect_all('pydantic_core')
datas += tmp_ret[0]; binaries += tmp_ret[1]; hiddenimports += tmp_ret[2]
tmp_ret = collect_all('pydub')
datas += tmp_ret[0]; binaries += tmp_ret[1]; hiddenimports += tmp_ret[2]
tmp_ret = collect_all('pygments')
datas += tmp_ret[0]; binaries += tmp_ret[1]; hiddenimports += tmp_ret[2]
tmp_ret = collect_all('python_multipart')
datas += tmp_ret[0]; binaries += tmp_ret[1]; hiddenimports += tmp_ret[2]
tmp_ret = collect_all('pytz')
datas += tmp_ret[0]; binaries += tmp_ret[1]; hiddenimports += tmp_ret[2]
tmp_ret = collect_all('requests')
datas += tmp_ret[0]; binaries += tmp_ret[1]; hiddenimports += tmp_ret[2]
tmp_ret = collect_all('rich')
datas += tmp_ret[0]; binaries += tmp_ret[1]; hiddenimports += tmp_ret[2]
tmp_ret = collect_all('ruff')
datas += tmp_ret[0]; binaries += tmp_ret[1]; hiddenimports += tmp_ret[2]
tmp_ret = collect_all('safehttpx')
datas += tmp_ret[0]; binaries += tmp_ret[1]; hiddenimports += tmp_ret[2]
tmp_ret = collect_all('semantic_version')
datas += tmp_ret[0]; binaries += tmp_ret[1]; hiddenimports += tmp_ret[2]
tmp_ret = collect_all('setuptools')
datas += tmp_ret[0]; binaries += tmp_ret[1]; hiddenimports += tmp_ret[2]
tmp_ret = collect_all('shellingham')
datas += tmp_ret[0]; binaries += tmp_ret[1]; hiddenimports += tmp_ret[2]
tmp_ret = collect_all('sniffio')
datas += tmp_ret[0]; binaries += tmp_ret[1]; hiddenimports += tmp_ret[2]
tmp_ret = collect_all('starlette')
datas += tmp_ret[0]; binaries += tmp_ret[1]; hiddenimports += tmp_ret[2]
tmp_ret = collect_all('tomlkit')
datas += tmp_ret[0]; binaries += tmp_ret[1]; hiddenimports += tmp_ret[2]
tmp_ret = collect_all('tqdm')
datas += tmp_ret[0]; binaries += tmp_ret[1]; hiddenimports += tmp_ret[2]
tmp_ret = collect_all('typer')
datas += tmp_ret[0]; binaries += tmp_ret[1]; hiddenimports += tmp_ret[2]
tmp_ret = collect_all('tzdata')
datas += tmp_ret[0]; binaries += tmp_ret[1]; hiddenimports += tmp_ret[2]
tmp_ret = collect_all('urllib3')
datas += tmp_ret[0]; binaries += tmp_ret[1]; hiddenimports += tmp_ret[2]
tmp_ret = collect_all('uvicorn')
datas += tmp_ret[0]; binaries += tmp_ret[1]; hiddenimports += tmp_ret[2]
tmp_ret = collect_all('websockets')
datas += tmp_ret[0]; binaries += tmp_ret[1]; hiddenimports += tmp_ret[2]
tmp_ret = collect_all('wheel')
datas += tmp_ret[0]; binaries += tmp_ret[1]; hiddenimports += tmp_ret[2]


a = Analysis(
 ['gradio_app.py'],
 pathex=[],
 binaries=binaries,
 datas=datas,
 hiddenimports=hiddenimports,
 hookspath=[],
 hooksconfig={},
 runtime_hooks=[],
 excludes=[],
 noarchive=False,
 module_collection_mode={'gradio': 'py',},
 optimize=0,
)
pyz = PYZ(a.pure)

exe = EXE(
 pyz,
 a.scripts,
 [],
 exclude_binaries=True,
 name='gradio_app',
 debug=False,
 bootloader_ignore_signals=False,
 strip=False,
 upx=True,
 console=True,
 disable_windowed_traceback=False,
 argv_emulation=False,
 target_arch=None,
 codesign_identity=None,
 entitlements_file=None,
)
coll = COLLECT(
 exe,
 a.binaries,
 a.datas,
 strip=False,
 upx=True,
 upx_exclude=[],
 name='gradio_app',
)

1. `Analysis` 部分

Analysis 是 PyInstaller 的核心类，用于分析 Python 脚本的依赖关系并收集打包所需的文件。

['gradio_app.py']:
指定要打包的主 Python 脚本文件。这里是 gradio_app.py，表示这是应用程序的入口脚本。
pathex=[]:
指定额外的路径，PyInstaller 会在这些路径中查找模块或文件。通常为空，PyInstaller 会自动处理标准路径。如果你的项目有非标准路径的依赖，可以在这里添加。
binaries=binaries:
指定额外的二进制文件（如 DLL 文件或共享库）。binaries 是一个预定义的列表，包含需要打包的非 Python 二进制依赖。如果为空，则 PyInstaller 自动检测。
datas=datas:
指定额外的非代码文件（如图像、配置文件、HTML 模板等）。datas 是一个列表，格式通常为 [(源路径, 目标路径)]。这些文件会被打包到最终的可执行文件中。
hiddenimports=hiddenimports:
指定 PyInstaller 无法自动检测的隐式导入模块。例如，某些动态导入的模块（如 Gradio 的依赖）需要手动列出，防止打包后缺少模块。
hookspath=[]:
指定自定义 PyInstaller 钩子文件的路径。钩子文件用于处理特定模块的打包逻辑（如 Gradio 的复杂依赖）。为空时使用默认钩子。
hooksconfig={}:
提供特定模块的钩子配置。某些模块需要额外的配置来正确打包，格式为字典。
runtime_hooks=[]:
指定运行时钩子脚本，这些脚本会在可执行文件启动时运行，用于动态修改环境（如设置环境变量）。
excludes=[]:
指定要从打包中排除的模块。用于减少包体积，排除不必要的模块。
noarchive=False:
是否禁用归档模式。如果为 True，PyInstaller 不会将文件打包为压缩归档，而是直接解压到临时目录。通常保持 False。
module_collection_mode={'gradio': 'py'}:
指定模块的收集模式。'gradio': 'py' 表示 Gradio 模块以源代码形式（.py 文件）收集，而不是编译为 .pyc 文件。这在调试或某些模块不兼容编译时有用。
optimize=0:
指定 Python 字节码优化的级别。
- 0: 无优化（默认）。
- 1: 移除 assert 语句。
- 2: 移除 assert 和文档字符串。
  通常设为 0 以保留调试信息。

2. `PYZ` 部分

PYZ 用于创建 Python 字节码的压缩归档文件（.pyz 文件），包含所有 Python 模块。

a.pure:
来自 Analysis 的纯 Python 模块列表（不包括 C 扩展模块）。PYZ 将这些模块打包为一个压缩归档，供可执行文件加载。

3. `EXE` 部分

EXE 定义了最终生成的可执行文件。

pyz:
上一步生成的 PYZ 对象，包含 Python 字节码。
a.scripts:
来自 Analysis 的脚本列表，通常包括主脚本（gradio_app.py）和 PyInstaller 的启动脚本。
[]:
额外的二进制文件列表，添加到可执行文件中。此处为空，依赖已在 Analysis 中处理。
exclude_binaries=True:
是否将二进制文件排除在可执行文件之外。如果为 True，二进制文件不会嵌入 .exe 文件，而是由 COLLECT 步骤单独收集到输出目录。这减少 .exe 文件大小。
name='gradio_app':
可执行文件的名称。生成的文件将命名为 gradio_app.exe（Windows）或 gradio_app（Linux/macOS）。
debug=False:
是否启用调试模式。如果为 True，会在运行时输出详细的调试信息（如模块加载日志）。通常设为 False。
bootloader_ignore_signals=False:
是否让 PyInstaller 的引导程序（bootloader）忽略系统信号（如 SIGINT）。通常保持默认值 False。
strip=False:
是否对可执行文件进行符号剥离（移除调试符号）。设为 True 可减小文件大小，但可能影响调试。通常设为 False。
upx=True:
是否使用 UPX（Ultimate Packer for Executables）压缩可执行文件。UPX 可以显著减小文件大小，但可能导致杀毒软件误报或兼容性问题。设为 True 表示启用。
console=True:
是否生成带有控制台窗口的可执行文件。
- True: 运行时会显示命令行窗口（适合调试或 CLI 应用）。
- False: 无控制台窗口（适合 GUI 应用）。
  Gradio 应用通常是 Web 应用，可能不需要控制台，但这里设为 True。
disable_windowed_traceback=False:
是否在 Windows GUI 模式下禁用错误跟踪。如果为 True，GUI 模式下的错误不会显示详细回溯。保持 False 以便调试。
argv_emulation=False:
是否模拟命令行参数传递（主要用于 macOS）。通常设为 False。
target_arch=None:
指定目标架构（如 x86_64 或 arm64）。为 None 时，PyInstaller 自动选择当前系统架构。
codesign_identity=None:
指定 macOS 代码签名的身份。为空表示不签名。
entitlements_file=None:
指定 macOS 代码签名的权限文件。为空表示使用默认权限。

4. `COLLECT` 部分

COLLECT 将所有文件（可执行文件、二进制文件、数据文件等）收集到一个输出目录。

exe:
上一步生成的 EXE 对象，即主可执行文件。
a.binaries:
来自 Analysis 的二进制文件列表，包含依赖的 DLL、共享库等。
a.datas:
来自 Analysis 的数据文件列表，包含非代码文件。
strip=False:
是否对收集的二进制文件进行符号剥离。保持 False 以保留调试信息。
upx=True:
是否对收集的二进制文件应用 UPX 压缩。与 EXE 部分的 upx 参数类似。
upx_exclude=[]:
指定不使用 UPX 压缩的文件列表。如果某些文件压缩后会导致问题，可以在这里列出。
name='gradio_app':
输出目录的名称。所有文件将被收集到 dist/gradio_app 目录下。

注意事项:

打包前确保在虚拟环境中安装了所有依赖
如果程序引用了动态库或特殊文件,需要使用–add-data或–add-binary添加
某些模块可能需要手动添加hidden-import
建议先使用-D选项测试,确认无误后再使用-F打包

这样的参数列表更加完整,包含了–noconfirm参数的使用说明。您可以根据具体需求选择合适的参数组合。

3. 实战案例：打包一个GUI应用

下面是一个完整的案例，展示如何打包一个使用tkinter的GUI应用。

3.1 示例程序代码

import tkinter as tk
from tkinter import messagebox

class SimpleApp:
 def __init__(self, root):
 self.root = root
 self.root.title("简单计算器")

 # 创建输入框
 self.num1 = tk.Entry(root)
 self.num1.pack()

 self.num2 = tk.Entry(root)
 self.num2.pack()

 # 创建按钮
 self.calc_button = tk.Button(root, text="计算", command=self.calculate)
 self.calc_button.pack()

 # 显示结果的标签
 self.result_label = tk.Label(root, text="结果：")
 self.result_label.pack()

 def calculate(self):
 try:
 n1 = float(self.num1.get())
 n2 = float(self.num2.get())
 result = n1 + n2
 self.result_label.config(text=f"结果：{result}")
 except ValueError:
 messagebox.showerror("错误", "请输入有效的数字！")

if __name__ == "__main__":
 root = tk.Tk()
 app = SimpleApp(root)
 root.mainloop()

3.2 打包配置文件

创建一个名为 app.spec 的配置文件：

# -*- mode: python ; coding: utf-8 -*-

block_cipher = None

a = Analysis(['your_script.py'],
 pathex=[],
 binaries=[],
 datas=[],
 hiddenimports=[],
 hookspath=[],
 hooksconfig={},
 runtime_hooks=[],
 excludes=[],
 win_no_prefer_redirects=False,
 win_private_assemblies=False,
 cipher=block_cipher,
 noarchive=False)

pyz = PYZ(a.pure, a.zipped_data,
 cipher=block_cipher)

exe = EXE(pyz,
 a.scripts,
 a.binaries,
 a.zipfiles,
 a.datas,
 [],
 name='MyApp',
 debug=False,
 bootloader_ignore_signals=False,
 strip=False,
 upx=True,
 upx_exclude=[],
 runtime_tmpdir=None,
 console=False,
 disable_windowed_traceback=False,
 target_arch=None,
 codesign_identity=None,
 entitlements_file=None,
 icon='icon.ico')

3.3 执行打包

使用配置文件进行打包：

pyinstaller app.spec

4. 常见问题及解决方案

4.1 找不到模块

如果打包后运行提示找不到某些模块，可以：

使用 --hidden-import 参数手动添加
在spec文件中的 hiddenimports 列表中添加

4.2 文件路径问题

在打包后的程序中，需要特别注意文件路径的处理：

import os
import sys

# 获取程序运行时的真实路径
if getattr(sys, 'frozen', False):
 application_path = os.path.dirname(sys.executable)
else:
 application_path = os.path.dirname(os.path.abspath(__file__))

4.3 减小文件体积

可以通过以下方法减小打包后的文件体积：

使用虚拟环境，只安装必要的依赖
使用 --exclude-module 排除不需要的模块
使用UPX压缩（如果可用）

实践建议

始终使用虚拟环境进行开发和打包
仔细检查依赖项，避免包含不必要的模块
在目标平台上测试打包后的程序
保存并管理spec文件，方便后续修改和重新打包
记录打包过程中的问题和解决方案

6. 环境相关注意事项

6.1 Python版本兼容性

建议使用与开发环境相同的Python版本进行打包
注意目标机器的系统架构(32位/64位)
某些第三方库可能与特定Python版本不兼容，需提前测试

6.2 虚拟环境使用

# 创建虚拟环境
python -m venv venv

# 激活虚拟环境
# Windows
venv\Scripts\activate
# Linux/Mac
source venv/bin/activate

# 安装依赖
pip install -r requirements.txt

6.3 依赖管理

使用pipreqs生成准确的依赖列表：

pip install pipreqs
pipreqs ./

定期更新requirements.txt
检查并移除未使用的依赖

Pyinstaller-打包gradio项目

Sun, 27 Apr 2025 00:42:01 +0800

由于gradio库中的代码都是pyi文件，而pyinstaller 在打包时默认库中的都是pyc文件，故而需要修改spec文件，指定对gradio库下的代码进行编译。

参考： https://cloud.tencent.com/developer/article/2503987

注意上面的链接中：

打包示例（20250426）：不推荐，打包出来的文件非常大

1 代码的例子


#gradio_example.py

import gradio as gr
import numpy as np
import logging
import sys
import os

# 配置日志
logging.basicConfig(
 level=logging.INFO,
 format='%(asctime)s - %(levelname)s - %(message)s',
 handlers=[
 logging.StreamHandler(sys.stdout)
 ]
)

def classify_text(text):
 try:
 # 这里我们使用一个简单的示例分类器
 # 在实际应用中，这里可以替换为你的机器学习模型
 if len(text) < 10:
 return "短文本"
 elif len(text) < 50:
 return "中等长度文本"
 else:
 return "长文本"
 except Exception as e:
 logging.error(f"分类过程中发生错误: {str(e)}")
 return f"错误: {str(e)}"

def main():
 try:
 # 创建 Gradio 界面
 demo = gr.Interface(
 fn=classify_text,
 inputs=gr.Textbox(label="输入文本", placeholder="请输入要分类的文本..."),
 outputs=gr.Textbox(label="分类结果"),
 title="文本长度分类器",
 description="这是一个简单的文本长度分类器示例。输入文本后，它会根据文本长度返回分类结果。",
 examples=[
 ["这是一个短文本"],
 ["这是一个中等长度的文本，包含了一些描述性的内容"],
 ["这是一个非常长的文本，包含了很多详细的信息和描述，可以用来测试分类器的性能，看看它如何处理较长的输入内容。"]
 ]
 )

 # 启动界面
 logging.info("正在启动 Gradio 界面...")
 demo.launch()
 except Exception as e:
 logging.error(f"程序启动失败: {str(e)}")
 input("按回车键退出...")

if __name__ == "__main__":
 main()

2 生成.spec文件并增加一行

gradio会有很多依赖库，这些都是要的，具体可以使用pip freeze 查看依赖

pyi-makespec --onefile --collect-all aiofiles --collect-all annotated_types --collect-all anyio --collect-all certifi --collect-all charset_normalizer --collect-all click --collect-all colorama --collect-all dateutil --collect-all fastapi --collect-all ffmpy --collect-all filelock --collect-all fsspec --collect-all gradio --collect-all gradio_client --collect-all groovy --collect-all h11 --collect-all httpcore --collect-all httpx --collect-all huggingface_hub --collect-all idna --collect-all jinja2 --collect-all lxml --collect-all markdown_it --collect-all markupsafe --collect-all mdurl --collect-all multipart --collect-all numpy --collect-all opencc --collect-all orjson --collect-all packaging --collect-all pandas --collect-all pillow --collect-all pip --collect-all pydantic --collect-all pydantic_core --collect-all pydub --collect-all pygments --collect-all python_multipart --collect-all pytz --collect-all requests --collect-all rich --collect-all ruff --collect-all safehttpx --collect-all semantic_version --collect-all setuptools --collect-all shellingham --collect-all sniffio --collect-all starlette --collect-all tomlkit --collect-all tqdm --collect-all typer --collect-all tzdata --collect-all urllib3 --collect-all uvicorn --collect-all websockets --collect-all wheel gradio_example.py

然后增加一行

module_collection_mode={'gradio': 'py',},

3 使用spec文件打包exe

pyinstaller gradio.spec

conda使用教程|pip使用教程|依赖安装_使用教程

Mon, 10 Mar 2025 14:00:34 +0800

📚 目录

1. Conda 基础与常用命令
2. Conda 安装与环境管理
3. Pip 使用指南
4. 镜像源配置
5. 将自定义代码包安装到环境
6. 常见问题与解决方案
7. Conda 与 Pip 区别对比
8. 将Python包发布到GitHub并通过pip安装

1. Conda 基础与常用命令

🚀 核心命令

# 环境管理
conda create -n env_name python=3.8 # 创建新环境
conda activate env_name # 激活环境
conda deactivate # 退出环境
conda env list # 列出所有环境
conda env remove -n env_name # 删除环境

# 包管理
conda install package_name # 安装包
conda install package_name=1.2.3 # 安装特定版本
conda install -c channel_name package_name # 指定通道安装
conda remove package_name # 卸载包
conda list # 列出已安装包
conda search package_name # 搜索包

# 系统维护
conda --version # 查看版本
conda update conda # 更新conda
conda update --all # 更新所有包
conda clean --all # 清理缓存

🔧 点击展开更多高级命令

# 环境导入导出
conda env export > environment.yml # 导出环境
conda env create -f environment.yml # 从文件创建环境
conda list --export > requirements.txt # 导出包列表

# 批量操作
conda create -n env_name python=3.8 numpy pandas # 创建时安装多个包
conda install --file requirements.txt # 批量安装
conda run -n env_name python script.py # 在特定环境运行命令

# 配置管理
conda config --show channels # 查看通道配置
conda config --add channels channel_name # 添加通道
conda config --remove channels channel_name # 移除通道
conda config --set channel_priority strict # 设置通道优先级
conda config --set auto_activate_base false # 禁用自动激活base

# 环境变量
conda env config vars set VAR_NAME=value # 设置环境变量
conda env config vars list # 查看环境变量
conda env config vars unset VAR_NAME # 删除环境变量

# 诊断工具
conda info --cache # 查看缓存位置
conda doctor # 检查环境完整性
conda list --revisions # 查看历史版本
conda install package_name --revision N # 回滚到特定版本

2. Conda 安装与环境管理

📦 Conda 安装

Linux 系统安装

# 下载Miniconda
wget https://repo.anaconda.com/miniconda/Miniconda3-latest-Linux-x86_64.sh

# 安装
bash Miniconda3-latest-Linux-x86_64.sh

# 初始化环境
cd ~
source ~/.bashrc

其他系统安装参考

操作系统	安装教程
Windows	CSDN教程
Ubuntu	CSDN教程

🏗️ 环境管理

创建环境

# 基本创建
conda create -n your_env_name python=3.8

# 创建时安装多个包
conda create -n your_env_name python=3.8 numpy scipy pandas

# 从现有环境克隆
conda create --name new_env --clone existing_env

删除环境

# 退出环境（如果正在使用）
conda deactivate

# 删除环境
conda remove -n ENV_NAME --all
# 或者
conda env remove -n ENV_NAME

⚠️ 注意：删除环境前请确保已退出该环境，使用 --all 标志会删除环境中的所有包。

3. Pip 使用指南

🔧 基本用法

版本管理

pip --version # 查看版本
pip install --upgrade pip # 升级pip

包管理

# 安装包
pip install package_name # 安装最新版本
pip install package_name==2.28.1 # 安装指定版本
pip install package_name>=2.0.0 # 安装最低版本

# 升级和卸载
pip install --upgrade package_name # 升级包
pip uninstall package_name # 卸载包

# 查看信息
pip list # 列出已安装包
pip show package_name # 显示包详情
pip search package_name # 搜索包（部分版本可用）

批量操作

# 批量安装
pip install -r requirements.txt

# 生成依赖文件
pip freeze > requirements.txt

# 生成项目依赖（推荐）
pip install pipreqs
pipreqs ./

💡 实用建议

虚拟环境使用

# 创建虚拟环境
python -m venv myenv

# 激活虚拟环境
source myenv/bin/activate # Linux/Mac
myenv\Scripts\activate # Windows

# 退出虚拟环境
deactivate

网络配置

# 使用代理
pip install package_name --proxy=http://代理地址:端口

# 使用国内镜像源
pip install package_name -i https://pypi.tuna.tsinghua.edu.cn/simple

# 信任主机（解决SSL问题）
pip install package_name --trusted-host pypi.org --trusted-host pypi.python.org

4. 镜像源配置

🌐 Pip 镜像源

常用国内镜像源

镜像源	地址	特点
清华大学	`https://pypi.tuna.tsinghua.edu.cn/simple`	速度快，更新及时
阿里云	`https://mirrors.aliyun.com/pypi/simple/`	稳定性好
中科大	`https://pypi.mirrors.ustc.edu.cn/simple/`	教育网友好
豆瓣	`http://pypi.douban.com/simple/`	老牌镜像
华为云	`https://repo.huaweicloud.com/pypi/simple/`	企业级稳定

临时使用

pip install package_name -i https://pypi.tuna.tsinghua.edu.cn/simple

永久配置

Linux/Mac 系统：

# 创建配置目录
mkdir -p ~/.pip

# 编辑配置文件
vim ~/.pip/pip.conf

Windows 系统：

# 配置文件位置：%USERPROFILE%\pip\pip.ini

配置内容：

[global]
index-url = https://pypi.tuna.tsinghua.edu.cn/simple
trusted-host = pypi.tuna.tsinghua.edu.cn

🔄 Conda 镜像源

常用国内镜像源

镜像源	主要地址	配置命令
清华大学	`https://mirrors.tuna.tsinghua.edu.cn/anaconda/pkgs/main/`	`conda config --add channels https://mirrors.tuna.tsinghua.edu.cn/anaconda/pkgs/main`
中科大	`https://mirrors.ustc.edu.cn/anaconda/pkgs/main/`	`conda config --add channels https://mirrors.ustc.edu.cn/anaconda/pkgs/main`
上海交大	`https://mirror.sjtu.edu.cn/anaconda/pkgs/main/`	`conda config --add channels https://mirror.sjtu.edu.cn/anaconda/pkgs/main`
阿里云	`https://mirrors.aliyun.com/anaconda/pkgs/main/`	`conda config --add channels https://mirrors.aliyun.com/anaconda/pkgs/main`

配置示例（清华源）

# 添加清华源
conda config --add channels https://mirrors.tuna.tsinghua.edu.cn/anaconda/pkgs/main
conda config --add channels https://mirrors.tuna.tsinghua.edu.cn/anaconda/pkgs/free
conda config --add channels https://mirrors.tuna.tsinghua.edu.cn/anaconda/cloud/conda-forge

# 显示通道地址
conda config --set show_channel_urls yes

conda-forge 源

# 添加conda-forge社区源
conda config --add channels conda-forge

管理配置

# 查看当前配置
conda config --show channels

# 恢复默认源
conda config --remove-key channels

# 移除特定通道
conda config --remove channels channel_name

5. 将自定义代码包安装到环境

📁 项目结构准备

project/
├── nirapi/ # 你的代码包
│ ├── __init__.py
│ ├── utils.py
│ ├── test.py
│ └── AnalysisClass/
│ └── __init__.py
└── setup.py # 安装配置文件

⚙️ 安装步骤

Step 1: 安装setuptools

pip install setuptools

Step 2: 创建setup.py文件

# coding=utf-8
from setuptools import setup, find_packages

setup(
 name="nirapi", # 包名
 version="1.0.0", # 版本号
 author="zata", # 作者
 author_email="your.email@example.com", # 邮箱
 description="This is a nir analyse api, written by zata", # 简短描述
 long_description=open("README.md").read() if os.path.exists("README.md") else "",
 long_description_content_type="text/markdown",

 # 自动发现包
 packages=find_packages(),

 # 或手动指定包
 # packages=["nirapi", "nirapi.AnalysisClass"],

 # 包含的数据文件
 package_data={
 'nirapi': ['*.txt', '*.json', '*.yaml'], # 包含特定文件类型
 },

 # 排除的文件
 exclude_package_data={
 '': ['.gitignore', '*.pyc', '__pycache__'],
 'nirapi': ['tests/*'],
 },

 # 依赖包
 install_requires=[
 'numpy>=1.19.0',
 'pandas>=1.2.0',
 # 其他依赖...
 ],

 # Python版本要求
 python_requires='>=3.6',

 # 分类信息
 classifiers=[
 "Development Status :: 3 - Alpha",
 "Intended Audience :: Developers",
 "License :: OSI Approved :: MIT License",
 "Programming Language :: Python :: 3",
 "Programming Language :: Python :: 3.6",
 "Programming Language :: Python :: 3.7",
 "Programming Language :: Python :: 3.8",
 ],
)

Step 3: 安装包

# 开发模式安装（推荐）
pip install -e .

# 或正常安装
pip install .

# 从其他位置安装
pip install /path/to/your/package

🔍 验证安装

# 测试导入
import nirapi
print(nirapi.__version__)

# 或
from nirapi import utils

6. 常见问题与解决方案

❗ 安装与配置问题

6.1 pip 忽略版本冲突

# 忽略依赖检查
pip install -r requirements.txt --no-dependencies

# 强制重新安装
pip install -r requirements.txt --force-reinstall

# 跳过失败的包继续安装
while read requirement; do
 pip install "$requirement" || echo "Failed to install $requirement, continuing..."
done < requirements.txt

6.2 conda 命令不可用

问题现象：安装后 conda --version 提示命令不存在

解决步骤：

验证安装位置

# 常见安装位置
ls ~/miniconda3/bin/conda # 默认位置
ls /opt/miniconda3/bin/conda # 容器环境常见位置

手动初始化

# 根据实际路径调整
/opt/miniconda3/bin/conda init bash
source ~/.bashrc

验证配置
```
conda --version
```

6.3 环境名称修改

# 方法：克隆 + 删除原环境
conda create --name new_env_name --clone old_env_name
conda env remove --name old_env_name

🐛 包管理问题

6.4 pip get_installed_distributions 报错

问题：from pip._internal.utils.misc import get_installed_distributions 报错

原因：pip 21.3+ 版本移除了该函数

解决方案：

# 降级pip到21.2版本
pip install pip==21.2

# 或使用新的替代方案
pip install importlib-metadata

6.5 依赖文件生成

# 方法1：使用pip freeze（包含所有包）
pip freeze > requirements.txt

# 方法2：使用pipreqs（仅项目依赖，推荐）
pip install pipreqs
pipreqs ./ --force # --force 覆盖现有文件

# 方法3：手动筛选核心依赖
pip freeze | grep -E "(numpy|pandas|requests)" > requirements.txt

🔧 环境问题

6.6 虚拟环境激活失败

# 检查虚拟环境路径
ls venv/bin/activate # Linux/Mac
ls venv\Scripts\activate # Windows

# 重新创建虚拟环境
rm -rf venv
python -m venv venv
source venv/bin/activate

6.7 包版本冲突

# 查看包依赖
pip show package_name

# 创建干净环境重新安装
conda create -n clean_env python=3.8
conda activate clean_env
pip install -r requirements.txt

7. Conda 与 Pip 区别对比

📊 详细对比表

维度	conda install	pip install
包管理范围	Python包 + 非Python依赖（C库、编译器等）	仅Python包
环境管理	与Conda环境紧密集成，强隔离	需要额外配置虚拟环境
包来源	Conda仓库（预编译，兼容性好）	PyPI仓库（可能需要编译）
依赖解决	严格的依赖解析，优先整体兼容性	相对宽松，可能出现版本冲突
安装速度	较快（预编译包）	可能较慢（需要编译）
包数量	相对较少但质量高	包数量庞大
适用场景	科学计算、数据科学、机器学习	通用Python开发、Web开发
平台支持	跨平台一致性好	依赖系统环境

🎯 使用建议

优先级策略

# 1. 在Conda环境中优先使用conda
conda install numpy pandas matplotlib

# 2. conda仓库没有的包使用pip
pip install some-special-package

# 3. 避免混合使用导致冲突

最佳实践

# ✅ 推荐做法
conda create -n myproject python=3.8
conda activate myproject
conda install numpy pandas scikit-learn # 科学计算包用conda
pip install flask # Web框架用pip

# ❌ 避免做法
pip install numpy # 在conda环境中用pip安装科学计算包

🔄 迁移建议

从pip迁移到conda

# 1. 创建conda环境
conda create -n new_env python=3.8

# 2. 尝试用conda安装主要依赖
conda install numpy pandas matplotlib

# 3. 剩余包用pip安装
pip install remaining-packages

环境同步

# 导出完整环境（包括pip安装的包）
conda env export > environment.yml

# 在新环境中重建
conda env create -f environment.yml

8. 将Python包发布到GitHub并通过pip安装

最后更新：2025-07-15

📦 创建Python包结构

构建以下目录结构：

your_package/
├── your_package/
│ ├── __init__.py
│ └── your_module.py
├── setup.py
├── README.md
├── LICENSE
└── requirements.txt

📝 编写关键文件

setup.py 示例：

from setuptools import setup, find_packages

setup(
 name='your_package_name',
 version='0.1.0',
 packages=find_packages(),
 install_requires=[
 'requests>=2.25.1',
 ],
 author='Your Name',
 author_email='your.email@example.com',
 description='A short description of your package',
 long_description=open('README.md').read(),
 long_description_content_type='text/markdown',
 url='https://github.com/yourusername/your_package',
 classifiers=[
 'Programming Language :: Python :: 3',
 'License :: OSI Approved :: MIT License',
 ],
)

your_package/init.py：

__version__ = '0.1.0'

🚀 初始化Git并上传到GitHub

git init
git add .
git commit -m "Initial commit"
git remote add origin https://github.com/yourusername/your_package.git
git branch -M main
git push -u origin main

🏷️ 创建GitHub Release（可选，但推荐）

访问GitHub仓库页面，点击"Releases" -> “Create a new release”
输入版本号（如v0.1.0），发布

📥 通过pip安装

直接从GitHub安装：

pip install git+https://github.com/yourusername/your_package.git

指定分支：

pip install git+https://github.com/yourusername/your_package.git@branch_name

指定版本（需要有release）：

pip install git+https://github.com/yourusername/your_package.git@v0.1.0

🌐 发布到PyPI（可选，允许标准pip安装）

安装工具：

pip install twine build

构建包：

python -m build

上传到PyPI：

twine upload dist/*

之后可使用：

pip install your_package_name

⚠️ 注意事项

确保setup.py信息准确
设置清晰的GitHub仓库描述和topics
使用MIT或其他合适的许可证
编写详细的README.md，包含安装和使用说明
发布到PyPI需注册账号并配置API token

🔧 实际案例演示

以我的包为例：

首先，无需任何修改，直接尝试pip install（我将其改为public）：

然而安装失败了。

将包发送给AI，AI帮助修改代码，包括创建nirapi目录，2个__init__.py文件，并修改setup.py：

推送到远程后，使用：

uv pip install git+https://github.com/zata-zhangtao/API_FOR_NIR_ANALYSIS.git@test_pip_git

安装成功！

让我们看看一些关键文件：

1. setup.py

# setup.py
# coding=utf-8
from setuptools import setup, find_packages

# Read the contents of README file
with open("README.md", "r", encoding="utf-8") as fh:
 long_description = fh.read()

setup(
 name="nirapi",
 version="1.0.0",
 author="zata",
 description="A Near-Infrared Spectroscopy Analysis API",
 long_description=long_description,
 long_description_content_type="text/markdown",
 packages=find_packages(),
 package_data={
 'nirapi': ['*.pkl'], # Include pickle files
 },
 include_package_data=True,
 python_requires=">=3.8",
 install_requires=[
 "numpy",
 "pandas",
 "scikit-learn",
 "scipy",
 "matplotlib",
 "seaborn",
 "plotly",
 "optuna",
 "pybaselines",
 "xgboost",
 "catboost",
 "lightgbm",
 "obspy",
 "tqdm",
 "requests",
 "pymysql",
 "joblib",
 ],
 classifiers=[
 "Development Status :: 4 - Beta",
 "Intended Audience :: Science/Research",
 "License :: OSI Approved :: MIT License",
 "Operating System :: OS Independent",
 "Programming Language :: Python :: 3",
 "Programming Language :: Python :: 3.8",
 "Programming Language :: Python :: 3.9",
 "Programming Language :: Python :: 3.10",
 "Programming Language :: Python :: 3.11",
 "Topic :: Scientific/Engineering :: Chemistry",
 "Topic :: Scientific/Engineering :: Information Analysis",
 ],
 keywords="NIR spectroscopy analysis machine-learning",
)

2. nirapi/init.py

"""
NIR API - A Near-Infrared Spectroscopy Analysis Package

This package provides tools for Near-Infrared spectroscopy analysis including:
- Data loading and preprocessing
- Machine learning models
- Visualization tools
- Analysis utilities
"""

__version__ = "1.0.0"
__author__ = "zata"
__description__ = "A Near-Infrared Spectroscopy Analysis API"

# Import main modules for easier access - only if dependencies are available
try:
 from . import utils
 from . import load_data
 from . import preprocessing
 from . import draw
 from . import analysis
 from . import ML_model
 from . import featsec
 from . import model_class

 # Make AnalysisClass available
 from . import AnalysisClass

 __all__ = [
 'utils',
 'load_data',
 'preprocessing',
 'draw',
 'analysis',
 'ML_model',
 'featsec',
 'model_class',
 'AnalysisClass'
 ]
except ImportError:
 # If dependencies are not available, provide a minimal interface
 __all__ = []

 def __getattr__(name):
 """Lazy import for modules when dependencies are available."""
 if name in ['utils', 'load_data', 'preprocessing', 'draw', 'analysis',
 'ML_model', 'featsec', 'model_class', 'AnalysisClass']:
 try:
 import importlib
 module = importlib.import_module(f'.{name}', __name__)
 return module
 except ImportError as e:
 raise ImportError(f"Module {name} requires additional dependencies: {e}")
 raise AttributeError(f"module '{__name__}' has no attribute '{name}'")

3. nirapi/AnalysisClass/init.py

"""
AnalysisClass subpackage for NIR API

Contains specialized analysis classes for different NIR analysis tasks.
"""

from . import Create_rec_task
from . import Create_train_task
from . import CreateTrainReport
from . import DataAnalysisReport

__all__ = [
 'Create_rec_task',
 'Create_train_task',
 'CreateTrainReport',
 'DataAnalysisReport'
]

python程序打包exe使用教程

Mon, 24 Feb 2025 00:00:00 +0000

Pystand

来源： https://www.zhihu.com/question/48776632/answer/2336654649

问题和注意事项

python嵌入包的版本要和开发时候的版本一致

我因为开发版本是3.11，搞了一个3.10的python嵌入包而报错

精简代码组织

PyStand.int 仅作为入口，复杂逻辑放入 script 目录的 main.py 或其他模块，方便调试和维护。路径配置：在 PyStand.int 中通过 sys.path.append 添加 script 或 script.egg 路径，确保模块可加载。

打包教程

来源： https://www.zhihu.com/question/48776632/answer/2336654649

Pyinstaller打包

如果打包成无控制台模式，你使用你打包好的软件运行程序时可能不报任何print。

打包时需要特别注意的源码编写规范

除了基本的 Python 编码规范之外,在准备程序进行打包时,还需要特别注意以下几点:

1.1 依赖管理

确保 requirements.txt 文件中列出了程序所有的依赖库
检查依赖库的版本兼容性,避免打包后出现兼容性问题
尽可能使用 pip freeze > requirements.txt 自动生成依赖列表

1.2 动态导入处理

程序中如果使用了动态导入,需要确保 PyInstaller 能够正确识别并打包
可以使用 PyInstaller --hiddenimport 选项手动指定隐藏依赖

1.3 平台兼容性

如果程序需要跨平台运行,需要确保代码本身具有良好的跨平台兼容性
针对不同平台,可能需要使用条件编译或运行时检测来适配

1.4 文件路径处理

程序中涉及文件读写操作时,需要注意处理相对路径和绝对路径
打包后的程序文件结构可能与开发环境不同,需要适当调整路径

1.5 图形界面兼容性

如果程序有图形界面,需要确保界面组件在打包后能正常工作
可能需要额外打包一些 GUI 库的依赖项

1.6 第三方库限制

某些第三方库可能不支持 PyInstaller 打包,需要提前了解并做好替代方案
对于不支持的库,可以考虑使用纯 Python 实现或寻找替代方案

1.7 运行时环境

确保程序在打包后的运行环境下能正常工作,例如环境变量、系统依赖等

目录结构

典型的目录结构 project_name/ ├── src/ │ ├── init.py │ └── main.py ├── tests/ │ ├── init.py │ └── test_main.py ├── resources/ │ ├── config.ini │ └── images/ ├── requirements.txt ├── setup.py └── README.md

文件地址如何引用

如果项目中使用到了文件

相对导入

在同一个包内部,可以使用相对导入的方式引用其他模块。 pythonCopyfrom . import some_module from .subpackage import another_module

绝对导入

跨包引用时,需要使用绝对导入的方式。 pythonCopyfrom project_name.modules import some_module from project_name.subpackage import another_module

注意事项

避免循环导入问题,可以使用 main 进行条件导入。保持导入语句的位置在文件顶部。优先使用绝对导入,相对导入仅在同一包内部使用。

打包成一个文件

pyinstaller -F main.py

打包成多个文件（软件启动速度会快点）

pyinstaller -D main.py

无控制台打包，多文件

pyinstaller -D -w main.py

其他参数

我来为您介绍 PyInstaller 的常用打包参数：

主要参数：

-F, --onefile 打包成一个独立的可执行文件
-D, --onedir 打包成一个文件夹(默认选项)
-w, --windowed 不显示命令行窗口(Windows系统)
-c, --console 显示命令行窗口(默认,Windows系统)
-n NAME 指定生成的可执行文件名
--clean 在构建之前清理临时文件

常用可选参数：

--icon=<FILE.ico> 指定可执行文件的图标
--add-data 添加额外的数据文件
--add-binary 添加额外的二进制文件
--paths 添加导入路径
--hidden-import 添加隐式导入的模块
--exclude-module 排除指定模块

高级参数：

--runtime-hook 指定运行时钩子脚本
--additional-hooks-dir 指定额外的钩子脚本目录
--version-file 指定版本文件
--manifest 指定manifest文件(Windows)
--upx-dir 指定UPX压缩工具目录
--noupx 禁用UPX压缩

使用示例：

# 打包成单个可执行文件
pyinstaller -F main.py

# 打包成单个文件并指定图标
pyinstaller -F main.py --icon=app.ico

# 打包时添加数据文件
pyinstaller -F main.py --add-data "data:data"

# 打包成文件夹并不显示控制台
pyinstaller -D -w main.py

使用配置文件.spec打包

pyinstaller your_project.spec

打包好的exe 使用时传入参数

在开发桌面应用程序时,经常需要在打包为可执行文件(EXE)后,能够向它传递参数,以实现不同的功能。下面就讲解如何在将 Python 脚本打包为 EXE 文件后,仍然可以向其传递参数。

1. 准备工作

首先,我们需要有一个简单的 Python 脚本,用于演示如何传递参数。假设我们有一个名为 main.py 的文件,内容如下:

import sys

if __name__ == '__main__':
 if len(sys.argv) > 1:
 arg1 = sys.argv[1]
 print(f"Argument passed: {arg1}")
 else:
 print("No arguments passed.")

这个脚本会检查命令行参数的数量,如果有参数传递,就会打印出第一个参数的值。

接下来,我们需要使用 PyInstaller 将这个 Python 脚本打包为可执行文件(EXE)。为此,我们创建一个名为 ExePack.py 的文件,内容如下:

import PyInstaller.__main__
import shutil
import os

PyInstaller.__main__.run([
 'main.py',
 '--onefile',
 '--name=MyApp',
 '--distpath=dist',
 '--workpath=build',
 '--specpath=.',
 '--noconsole'
])

# 删除 build 文件夹
shutil.rmtree('build', ignore_errors=True)
# 删除 .spec 文件
os.remove('MyApp.spec')

这个脚本使用 PyInstaller 将 main.py 打包为一个名为 MyApp.exe 的可执行文件,并输出到 dist 文件夹。

2. 传递参数

现在,我们需要编写一个脚本,用于运行打包好的 EXE 文件并传递参数。创建一个名为 args2exe.py 的文件,内容如下:

import subprocess
import os

def run_exe_with_args(exe_path, *args):
 """运行 exe 文件并传入参数"""
 if not os.path.exists(exe_path):
 print(f"文件不存在: {exe_path}")
 return

 command = [exe_path] + list(args)
 result = subprocess.run(command, capture_output=True, text=True)

 print("标准输出:", result.stdout)

if __name__ == '__main__':
 exe_path = os.path.join('dist', 'MyApp.exe')
 run_exe_with_args(exe_path, '参数1', '参数2')

这个脚本定义了一个 run_exe_with_args 函数,用于运行打包好的 EXE 文件并传递参数。在 if __name__ == '__main__' 部分,我们调用这个函数,传递 '参数1' 和 '参数2' 作为参数。

3. 运行

首先,运行 ExePack.py 脚本,将 main.py 打包为 MyApp.exe 可执行文件。
然后,运行 args2exe.py 脚本。这将启动 MyApp.exe 并传递参数 '参数1' 和 '参数2'。

在控制台上,你应该能看到以下输出:

Argument passed: 参数1

这就是在打包好的 EXE 文件中传递参数的方法。通过使用 subprocess 模块,我们可以运行 EXE 文件并向其传递参数,从而实现更灵活的应用程序功能。

构建与打包 on 扎塔-Zata

npm使用教程

目录

常用命令

快速参考

1. 什么是 npm？

2. 安装 npm

3. 核心概念

4. 常用命令详解

npm init

npm install

npm uninstall

npm update

npm run

npm list

5. 深入理解 package.json

6. 版本管理：语义化版本 (SemVer)

7. 进阶命令

npm outdated

npm ci

npm audit

npm view

npx

8. 最佳实践和技巧

npm 相关问题解决教程

1. 前端启动问题

问题现象

解决方案

临时解决方案

永久解决方案1：修改 package.json（推荐）

永久解决方案2：修改 vite.config.ts

永久解决方案3：使用环境变量

2. npm 脚本命令详解

内置脚本 vs 自定义脚本

内置脚本（不需要 run）

自定义脚本（必须使用 run）

为什么 npm start 不需要 run？

实际验证

3. 常用 npm 脚本配置

基础配置

进阶配置

4. 常见问题排查

端口占用问题

清除缓存

网络问题

5. 脚本最佳实践

脚本命名约定

参数传递

6. 问题解决总结

包管理工具poetry使用教程

1. 什么是 Poetry？

2. 安装 Poetry

2.1 安装 Poetry

2.2 验证安装

2.3 配置 Poetry

3. 创建一个新项目

3.1 初始化项目

3.2 使用现有项目

4. 管理依赖

4.1 添加依赖

4.2 移除依赖

4.3 查看依赖

4.4 锁定依赖

5. 管理虚拟环境

5.1 激活虚拟环境

5.2 在虚拟环境中运行命令

5.3 检查虚拟环境

6. 打包和发布项目

6.1 配置项目

6.2 构建项目

6.3 发布到 PyPI

7. 常用命令速查

8. 实用技巧

8.1 使用特定 Python 版本

8.2 导出 requirements.txt

8.3 管理多个依赖组

8.4 解决依赖冲突

8.5 集成 IDE

9. 常见问题

9.1 Poetry 安装依赖很慢？

`npm init`

`npm install`

`npm uninstall`

`npm update`

`npm run`

`npm list`

5. 深入理解 `package.json`

`npm outdated`

`npm ci`

`npm audit`

`npm view`

`npx`

内置脚本（不需要 `run`）

自定义脚本（必须使用 `run`）

为什么 `npm start` 不需要 `run`？

`pipx` 的核心优势：

1. 安装 `pipx`

2. `pipx` 的基本使用

3. `pipx` 的进阶使用

何时使用 `pipx` vs `pip`?

创建和管理虚拟环境 (`uv venv`)

安装包 (`uv pip install`)

卸载包 (`uv pip uninstall`)

列出已安装的包 (`uv pip list`)

生成依赖文件 (`uv pip freeze`)

从依赖文件安装 (`uv pip install -r`, `uv pip sync`)

编译依赖 (`uv pip compile`)

使用 `pyproject.toml`

临时执行包 (`uvx`)

缓存管理 (`uv cache`)