> 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/ask/flat/chapter-21-development-environments/di-21.4-jie-python-kai-fa-huan-jing.md). # 21.4 Python Development Environment This section introduces how to configure the Python development environment on FreeBSD. ## FreeBSD Python Overview In FreeBSD, different Python versions are packaged separately. In other words, Python 3.11 and Python 3.13 are different packages. For example, Port `lang/python311` corresponds to Python 3.11, `lang/python313` corresponds to Python 3.13, and `lang/python314` corresponds to Python 3.14. In FreeBSD Ports, the level of pkg binary package support for different Python versions varies as versions evolve. For example, the current `lang/python` (which is actually just a meta package, i.e., a dependency package pointing to other packages) defaults to Python 3.11: This mapping is defined by the source file **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 ``` Therefore, other Python packages installed via pkg (such as Python-XX) will also be built based on this version by default; other software that depends on Python will also depend on this version. However, Python packages or software built based on the latest Python version may have incomplete support on FreeBSD (they may need to be built through Ports, or may be unusable). > **Tip** > > This is similar to the Python USE flag in Gentoo Linux. Once a Python version is specified, all software that depends on Python will use the selected version. ## Installing Python * Install Python and py-pip packages using pkg: ```sh # pkg install python devel/py-pip ``` * Or install using Ports: ```sh # cd /usr/ports/lang/python/ && make install clean # cd /usr/ports/devel/py-pip/ && make install clean ``` If you need to install a specific version of Python, it is recommended to specify the Python version globally through USE. ## How to Specify the Python Version for Ports Compilation? > **Note** > > In practice, the version that `lang/python` points to is ultimately controlled by the USE setting. Assuming you need to change the default compilation version from 3.14 to 3.12: ```sh # echo "DEFAULT_VERSIONS+= python=3.12 python3=3.12" >> /etc/make.conf ``` This sets the default Python version to 3.12 and appends it to the **/etc/make.conf** file. > **Tip** > > If only a single parameter is set, a warning is normal. See [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), which documents the Python version configuration warning issue. > > ```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 > ``` ## Managing Python with uv uv is a highly efficient Python package manager and dependency resolver. ### Installing uv * Install using pkg: ```sh # pkg install python devel/py-uv ``` * Or install using Ports: ```sh # cd /usr/ports/devel/py-uv/ # make install clean ``` ### Using uv Start project management with the following commands. ```sh $ mkdir project $ cd project $ uv init ``` The output is as follows: ```sh Initialized project `project` ``` This command automatically generates a **pyproject.toml** file, establishing the project metadata specification. ```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 ``` The example **main.py** is a demo source code. Run it and observe the output: ```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 creates a **.venv** folder in the project root directory by default. Install several packages using 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 ``` Use uvx to create a temporary, isolated runtime environment to execute code: ```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 ``` Delete the relevant files to clean up the project, such as **.venv**, **uv.lock**, **pyproject.toml**, and **.python-version**. ## References * FreeBSD Project. Ports/DEFAULT\_VERSIONS\[EB/OL]. \[2026-03-26]. . Official documentation for FreeBSD Ports default version configuration. * FreeBSD Project. Python\[EB/OL]. \[2026-03-26]. . Official guide for configuring the Python development environment on FreeBSD. --- # 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: ``` GET https://book.bsdcn.org/ask/flat/chapter-21-development-environments/di-21.4-jie-python-kai-fa-huan-jing.md?ask= ``` The question should be specific, self-contained, and written in natural language. 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.