40.4 Python 开发环境

本节介绍 FreeBSD 上的 Python 开发环境配置方法。

FreeBSD Python 概述

在 FreeBSD 中，不同的 Python 版本分别打包。换言之，Python 3.11 和 Python 3.13 属于不同的包，例如 Port lang/python311 对应 Python 3.11，lang/python313 对应 Python 3.13，lang/python314 对应 Python 3.14。

在 FreeBSD Ports 中，不同版本 Python 的 pkg 二进制包支持程度随版本演进而有所差异。

例如，当前 lang/python（实际上仅为元包，即指向其他软件包的依赖包）默认指向 Python 3.11：

这种指称关系由源代码文件 Mk/bsd.default-versions.mk 定义：

# Possible values: 3.10, 3.11, 3.12, 3.13, 3.13t, 3.14
PYTHON_DEFAULT?=	3.11
# Possible values: 2.7
PYTHON2_DEFAULT?=	2.7

则通过 pkg 安装的其他 Python 包（如 Python-XX）在默认情况下也会以此版本为基础构建；其他依赖 Python 的软件同样依赖该版本。

而以最新 Python 版本为基础构建的 Python 包或软件，在 FreeBSD 上的支持可能不够完善（可能需要通过 Ports 构建，或者无法使用）。

技巧

这类似于 Gentoo Linux 中的 Python USE 标记。只要指定了 Python 版本，所有依赖 Python 的软件都会使用所选择的版本。

安装 Python

• 使用 pkg 安装 Python 和 py-pip 包：

# pkg install python devel/py-pip

• 也可通过 Ports 安装：

# cd /usr/ports/lang/python/ && make install clean
# cd /usr/ports/devel/py-pip/ && make install clean

如需安装特定版本的 Python，建议统一通过 USE 全局指定 Python 版本。

如何指定 Ports 编译的 Python 版本？

注意

实际上，lang/python 指向的版本最终是由 USE 设置控制的。

假设需要将默认编译版本从 3.14 改为 3.12：

# echo "DEFAULT_VERSIONS+= python=3.12 python3=3.12" >> /etc/make.conf

将默认 Python 版本设置为 3.12，并将其追加到 /etc/make.conf 文件中。

技巧

如果只设置了单个参数，出现警告是正常的，见 Bug 243034 - Mk/Uses/python.mk: WARNING when python version is set to non-default version in make.conf，记录 Python 版本配置警告问题。

/!\ WARNING /!\

PYTHON_DEFAULT must be a version present in PYTHON2_DEFAULT or PYTHON3_DEFAULT,
if you want more Python flavors, set BUILD_ALL_PYTHON_FLAVORS in your make.conf

通过 uv 管理 Python

uv 是一款执行效率极高的 Python 包管理器与依赖解析器。

安装 uv

• 使用 pkg 安装：

# pkg install python devel/py-uv

• 也可通过 Ports 安装：

# cd /usr/ports/devel/py-uv/
# make install clean

使用 uv

通过以下命令启动项目管理。

$ mkdir project
$ cd project
$ uv init

输出如下：

Initialized project `project`

该命令将自动生成 pyproject.toml 文件，建立项目元数据规范。

~/project $ ls -al
total 23
drwxr-xr-x   2 ykla ykla   6  5月 25 00:29 .
drwxr-xr-x  33 ykla ykla  52  5月 25 00:28 ..
-rw-r--r--   1 ykla ykla   5  5月 25 00:29 .python-version
-rw-r--r--   1 ykla ykla  85  5月 25 00:29 main.py
-rw-r--r--   1 ykla ykla 153  5月 25 00:29 pyproject.toml
-rw-r--r--   1 ykla ykla   0  5月 25 00:29 README.md

示例 main.py 是演示源代码，运行后观察输出：

~/project $ uv run main.py
Using CPython 3.11.15 interpreter at: /usr/local/bin/python3.11
Creating virtual environment at: .venv
Hello from project!

uv 默认会在项目根目录下创建 .venv 文件夹。

使用 uv 安装若干软件包：

~/project $ uv add cowsay pyjokes
Resolved 3 packages in 2.51s
Prepared 2 packages in 2.09s
Installed 2 packages in 10ms
 + cowsay==6.1
 + pyjokes==0.8.3

使用 uvx 创建临时的、隔离的运行环境执行代码：

$ uvx --with cowsay --with pyjokes python -c "import cowsay; import pyjokes; print(cowsay.cow(pyjokes.get_joke()))"
  ____________________________________________
| One person's error is another person's data. |
  ============================================
                                            \
                                             \
                                               ^__^
                                               (oo)\_______
                                               (__)\       )\/\
                                                   ||----w |
                                                   ||     ||
None

删除相关文件即可清除项目，如 .venv、uv.lock、pyproject.toml 和 .python-version 等。

参考文献

• FreeBSD Project. Ports/DEFAULT_VERSIONS[EB/OL]. [2026-03-26]. https://wiki.freebsd.org/Ports/DEFAULT_VERSIONS. FreeBSD Ports 默认版本配置官方说明。
• FreeBSD Project. Python[EB/OL]. [2026-03-26]. https://wiki.freebsd.org/Python. 在 FreeBSD 上配置 Python 开发环境的官方指南。