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:

# 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:

# pkg install python devel/py-pip

• Or install using Ports:

# 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:

# 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, which documents the Python version configuration warning issue.

/!\ 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:

# pkg install python devel/py-uv

• Or install using Ports:

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

Using uv

Start project management with the following commands.

$ mkdir project
$ cd project
$ uv init

The output is as follows:

Initialized project `project`

This command automatically generates a pyproject.toml file, establishing the project metadata specification.

~/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:

~/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:

~/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:

$ 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]. https://wiki.freebsd.org/Ports/DEFAULT_VERSIONS. Official documentation for FreeBSD Ports default version configuration.
• FreeBSD Project. Python[EB/OL]. [2026-03-26]. https://wiki.freebsd.org/Python. Official guide for configuring the Python development environment on FreeBSD.