Use pip3 Safely with a Project Virtual Environment

You will create an isolated Python environment, install a pinned package into it, check what is installed, and remove it again. Allow about 10 minutes, plus download time. The commands use pip3, with python3 -m pip shown where binding pip to a particular interpreter matters.

Before you start

You need a shell, Python 3, and the python3-pip package. On this machine, the package is version 24.0+dfsg-1ubuntu1.3+esm3 and /usr/bin/pip3 reports pip 24.0 for Python 3.12. The installed man pages are older: both identify pip 1.5.6 and describe the historical Debian pip/pip3 split. For the commands below, the current executable and its help output are the authority.

Check which executable you are about to use:

command -v pip3
pip3 --version
python3 -m pip --version

Expected output includes a path and a line similar to pip 24.0 ... (python 3.12). If those commands name different Python installations, use python3 -m pip consistently, or activate the intended virtual environment first.

Checkpoint 1: create and enter the environment

1. From your project directory, create a local environment named .venv:

   python3 -m venv .venv

   If this fails with a message about ensurepip, install the distribution's python3-venv package with your system package manager. That is an administrative change, so review the package name for your distribution before using sudo.

2. Activate it in the current shell:

   source .venv/bin/activate

   Now verify the interpreter and pip belong to the environment:

   command -v python
   python -m pip --version

   The paths should contain /.venv/. Activation only changes this shell. Leave it later with deactivate.

Keep .venv out of version control. Add it to the project's .gitignore if the project is tracked. The environment is disposable: deleting that directory removes the environment, but it does not remove packages from your system Python.

Checkpoint 2: install a package deliberately

Install a named distribution from the configured package index. This example pins Requests to one version so another run does not silently choose a newer release:

python -m pip install 'requests==2.32.3'

pip resolves and installs dependencies as needed. A successful run ends with a line beginning Successfully installed. Exact dependency versions and messages vary with the Python version, platform and index contents.

Before making a real change, you can ask pip to resolve the same request without installing it:

python -m pip install --dry-run 'requests==2.32.3'

--dry-run reports what would happen. It may still contact the package index. Do not treat a package name alone as a trust decision: inspect its project, source and release history before installing code, especially when using a third-party index.

For repeatable project setup, put requirements in a file such as requirements.txt, then install it:

python -m pip install -r requirements.txt

Only use a requirements file you have reviewed. It can contain options and references to external package sources, not just simple names.

Checkpoint 3: inspect and test the result

List the environment's packages and their versions:

python -m pip list

For one distribution, show its metadata and installation location:

python -m pip show requests

Check that installed distributions have compatible declared dependencies:

python -m pip check

Success is reported as No broken requirements found.. This checks dependency metadata; it does not prove that an application behaves correctly. Run the project's own tests as a separate step.

If you need a record of the environment, freeze writes installed distributions in requirements format:

python -m pip freeze > requirements-lock.txt
sed -n '1,20p' requirements-lock.txt

Review that file before committing it. It records what is installed, including transitive dependencies, and may include packages you did not mean to make part of the application.

Remove or rebuild without damaging the host Python

To remove the example package, first make sure the environment is active, then ask pip to confirm the deletion:

python -m pip uninstall requests

Answer y only after checking the package name. The command can remove files belonging to that distribution. For a reviewed requirements file, python -m pip uninstall -r requirements.txt is also supported. Avoid -y in recovery work until you have checked the target list.

If the environment is confused, the simplest recovery is to leave it and recreate it:

deactivate
rm -rf .venv
python3 -m venv .venv
source .venv/bin/activate
python -m pip install -r requirements.txt

On Debian and Ubuntu, do not use pip to overwrite the distribution-managed system Python unless you have a specific, reviewed reason. Prefer a virtual environment for applications, or the distribution package manager for system software. A permission error is a signal to reconsider the target, not an instruction to add sudo. pip 24.0 also exposes --break-system-packages; that option deliberately permits changes to an externally managed installation and should be treated as a last resort.

Configuration and common traps

pip reads command-line options, environment variables and configuration files. A setting such as an alternate index, proxy or trusted host can change where packages come from. Inspect the active configuration before debugging a surprising install:

python -m pip config debug

For a one-off clean diagnostic, ignore user and site configuration:

python -m pip --isolated --version

Do not put passwords in command history or URLs. Prefer a properly managed credential mechanism, and avoid --trusted-host unless you understand why certificate verification cannot be used. The default index shown by this installed pip is https://pypi.org/simple; an organisation may intentionally configure another index.

If a script must never run outside a virtual environment, add --require-virtualenv to its pip invocation. This makes an accidental global install fail instead of changing the wrong interpreter.