> For the complete documentation index, see [llms.txt](https://book.bsdcn.org/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://book.bsdcn.org/di-40-zhang-kai-fa-huan-jing/di-40.4-jie-python-kai-fa-huan-jing.md).

# 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** 定义：

```make
# 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 包：

```sh
# pkg install python devel/py-pip
```

* 也可通过 Ports 安装：

```sh
# 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：

```sh
# 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](https://bugs.freebsd.org/bugzilla/show_bug.cgi?id=243034)，记录 Python 版本配置警告问题。
>
> ```sh
> /!\ 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 安装：

```sh
# pkg install python devel/py-uv
```

* 也可通过 Ports 安装：

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

### 使用 uv

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

```sh
$ mkdir project
$ cd project
$ uv init
```

输出如下：

```sh
Initialized project `project`
```

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

```sh
~/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** 是演示源代码，运行后观察输出：

```sh
~/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 安装若干软件包：

```sh
~/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 创建临时的、隔离的运行环境执行代码：

```sh
$ 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 开发环境的官方指南。


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://book.bsdcn.org/di-40-zhang-kai-fa-huan-jing/di-40.4-jie-python-kai-fa-huan-jing.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.