pyo3 build or run failed (ld -lpython) when using a python manager like `uv` or any `venv`

Hello,

I’ve faced quite a few challenges when building and running projects with PyO3 on systems that are fully managed by Python virtual environments. Most of the time, the issue boils down to errors like ld -lpython3.X not found. I wanted to share a workaround that worked for me.

On UNIX systems, you can see the specific directories ld searches by running the following command:

ld --verbose | grep SEARCH_DIR | tr -s ' ;' \\012

This will output something like:

SEARCH_DIR("=/usr/local/lib/x86_64-linux-gnu")
SEARCH_DIR("=/lib/x86_64-linux-gnu")
SEARCH_DIR("=/usr/lib/x86_64-linux-gnu")
SEARCH_DIR("=/usr/lib/x86_64-linux-gnu64")
SEARCH_DIR("=/usr/local/lib64")
SEARCH_DIR("=/lib64")
SEARCH_DIR("=/usr/lib64")
SEARCH_DIR("=/usr/local/lib")
SEARCH_DIR("=/lib")
SEARCH_DIR("=/usr/lib")
SEARCH_DIR("=/usr/x86_64-linux-gnu/lib64")
SEARCH_DIR("=/usr/x86_64-linux-gnu/lib")

However, when using tools like uv, anaconda, etc., the Python installation is often standalone, and ld doesn’t know where to find the necessary libraries.

For example, with uv, the Python library is typically located in ~/.local/share/uv/python/cpython-{version}/lib. To fix this, you can configure ld to include this directory in its search path. For Python 3.13.1 on x86_64 Linux, you can do the following:

echo "/home/USER/.local/share/uv/python/cpython-3.13.1-linux-x86_64-gnu/lib" | sudo tee /etc/ld.so.conf.d/uv_python.conf

Then, reload the linker configuration using:

sudo ldconfig

After that, ld should be able to find the Python libraries correctly.

You can adapt this approach for any Python environment manager. I haven’t found clear documentation on this issue, so I hope this solution helps others who run into the same problem.

Start by reproducing the reported ld -lpython3.X not found failure with a Python installation managed by uv or another virtual environment. Use the issue's ld --verbose command to inspect linker search paths and compare them with the standalone Python library location. Done means establishing whether the failure is actionable in PyO3 and documenting or resolving the supported behavior.