Installing Packages - Python Packaging User Guide

Installing Packages - Python Packaging User Guide
Hide navigation sidebar
Hide table of contents sidebar
Skip to content
Python Packaging User Guide
Overview of Python Packaging
The Packaging Flow
Tutorials
Guides
Discussions
Toggle navigation of Discussions
Versioning
Deploying Python applications
pip vs easy_install
install_requires vs requirements files
Distribution package vs. import package
Package Formats
src layout vs flat layout
Is
setup.py
deprecated?
Single-sourcing the Project Version
Supporting downstream packaging
PyPA specifications
Toggle navigation of PyPA specifications
Package Distribution Metadata
Toggle navigation of Package Distribution Metadata
Names and normalization
Core metadata specifications
Version specifiers
Dependency specifiers
pyproject.toml
specification
Dependency Groups
Inline script metadata
Platform compatibility tags
Well-known Project URLs in Metadata
glob
patterns
License Expression
Package Installation Metadata
Toggle navigation of Package Installation Metadata
Recording installed projects
Entry points specification
Recording the Direct URL Origin of installed distributions
Direct URL Data Structure
Python Virtual Environments
Externally Managed Environments
Package Distribution File Formats
Toggle navigation of Package Distribution File Formats
Source distribution format
Binary distribution format
Package Index Interfaces
Toggle navigation of Package Index Interfaces
The
.pypirc
file
Simple repository API
File Yanking
Index hosted attestations
Project Status Markers
Python Description Formats
Toggle navigation of Python Description Formats
build-details.json
Toggle navigation of build-details.json
v1.0
Reproducible Environments
Toggle navigation of Reproducible Environments
pylock.toml
Specification
PyPA schemas
Project Summaries
Glossary
How to Get Support
Contribute to this guide
News
View this page
Edit this page
Toggle table of contents sidebar
Installing Packages
This section covers the basics of how to install Python
packages
It’s important to note that the term “package” in this context is being used to
describe a bundle of software to be installed (i.e. as a synonym for a
distribution
). It does not refer to the kind
of
package
that you import in your Python source code
(i.e. a container of modules). It is common in the Python community to refer to
distribution
using the term “package”. Using
the term “distribution” is often not preferred, because it can easily be
confused with a Linux distribution, or another larger software distribution
like Python itself.
Requirements for Installing Packages
This section describes the steps to follow before installing other Python
packages.
Ensure you can run Python from the command line
Before you go any further, make sure you have Python and that the expected
version is available from your command line. You can check this by running:
Unix/macOS
python3
--version
Windows
py --version
You should get some output like
Python
3.6.3
. If you do not have Python,
please install the latest 3.x version from
python.org
or refer to the
Installing Python
section of the Hitchhiker’s Guide to Python.
Note
If you’re a newcomer and you get an error like this:
>>>
python3
--
version
Traceback (most recent call last):
File
""
, line
, in

NameError
name 'python3' is not defined
It’s because this command and other suggested commands in this tutorial
are intended to be run in a
shell
(also called a
terminal
or
console
). See the Python for Beginners
getting started tutorial
for
an introduction to using your operating system’s shell and interacting with
Python.
Note
If you’re using an enhanced shell like IPython or the Jupyter
notebook, you can run system commands like those in this tutorial by
prefacing them with a
character:
In [1]: import sys
!{sys.executable} --version
Python 3.6.3
It’s recommended to write
{sys.executable}
rather than plain
python
in
order to ensure that commands are run in the Python installation matching
the currently running notebook (which may not be the same Python
installation that the
python
command refers to).
Note
Due to the way most Linux distributions are handling the Python 3
migration, Linux users using the system Python without creating a virtual
environment first should replace the
python
command in this tutorial
with
python3
and the
python
-m
pip
command with
python3
-m
pip
--user
. Do
not
run any of the commands in this tutorial with
sudo
: if you get a
permissions error, come back to the section on creating virtual environments,
set one up, and then continue with the tutorial as written.
Ensure you can run pip from the command line
Additionally, you’ll need to make sure you have
pip
available. You can
check this by running:
Unix/macOS
python3
-m
pip
--version
Windows
py -m pip --version
If you installed Python from source, with an installer from
python.org
, or
via
Homebrew
you should already have pip. If you’re on Linux and installed
using your OS package manager, you may have to install pip separately, see
Installing pip/setuptools/wheel with Linux Package Managers
If
pip
isn’t already installed, then first try to bootstrap it from the
standard library:
Unix/macOS
python3
-m
ensurepip
--default-pip
Windows
py -m ensurepip --default-pip
If that still doesn’t allow you to run
python
-m
pip
Securely Download
get-pip.py
Run
python
get-pip.py
This will install or upgrade pip.
Additionally, it may install
Setuptools
and
wheel
if they’re
not installed already.
Warning
Be cautious if you’re using a Python install that’s managed by your
operating system or another package manager. get-pip.py does not
coordinate with those tools, and may leave your system in an
inconsistent state. You can use
python
get-pip.py
--prefix=/usr/local/
to install in
/usr/local
which is designed for locally-installed
software.
Ensure pip is up to date
Make sure you have the latest features and fixes, and support for the latest
Python packaging specifications.
Unix/macOS
python3
-m
pip
install
--upgrade
pip
Windows
py -m pip install --upgrade pip
Optionally, create a virtual environment
See
section below
for details,
but here’s the basic
venv
command to use on a typical Linux system:
Unix/macOS
python3
-m
venv
tutorial_env
source
tutorial_env/bin/activate
Windows
py -m venv tutorial_env
tutorial_env\Scripts\activate
This will create a new virtual environment in the
tutorial_env
subdirectory,
and configure the current shell to use it as the default
python
environment.
Creating Virtual Environments
Python “Virtual Environments” allow Python
packages
to be installed in an isolated location for a particular application,
rather than being installed globally. If you are looking to safely install
global command line tools,
see
Installing stand alone command line tools
Imagine you have an application that needs version 1 of LibFoo, but another
application requires version 2. How can you use both these applications? If you
install everything into /usr/lib/python3.6/site-packages (or whatever your
platform’s standard location is), it’s easy to end up in a situation where you
unintentionally upgrade an application that shouldn’t be upgraded.
Or more generally, what if you want to install an application and leave it be?
If an application works, any change in its libraries or the versions of those
libraries can break the application.
Also, what if you can’t install
packages
into the
global site-packages directory? For instance, on a shared host.
In all these cases, virtual environments can help you. They have their own
installation directories and they don’t share libraries with other virtual
environments.
Currently, there are two common tools for creating Python virtual environments:
venv
is available by default in Python 3.3 and later, and installs
pip
into created virtual environments in Python 3.4 and later
(Python versions prior to 3.12 also installed
Setuptools
).
virtualenv
needs to be installed separately, but supports Python 2.7+
and Python 3.3+, and
pip
Setuptools
and
wheel
are
installed into created virtual environments by default. Note that
setuptools
is no longer
included by default starting with Python 3.12 (and
virtualenv
follows this behavior).
The basic usage is like so:
Using
venv
Unix/macOS
python3
-m
venv