mirror of
https://github.com/kennethreitz/pipenv.git
synced 2026-06-05 14:50:16 +00:00
Matt Davis
258 lines
11 KiB
ReStructuredText
258 lines
11 KiB
ReStructuredText
.. _virtualenvironments-ref:
|
||
|
||
=============================
|
||
Pipenv & Virtual Environments
|
||
=============================
|
||
|
||
.. image:: https://farm3.staticflickr.com/2943/33485660921_dfc0494739_k_d.jpg
|
||
|
||
This tutorial walks you through installing and using Python packages.
|
||
|
||
It will show you how to install and use the necessary tools and make strong
|
||
recommendations on best practices. Keep in mind that Python is used for a great
|
||
many different purposes, and precisely how you want to manage your dependencies
|
||
may change based on how you decide to publish your software. The guidance
|
||
presented here is most directly applicable to the development and deployment of
|
||
network services (including web applications), but is also very well suited to
|
||
managing development and testing environments for any kind of project.
|
||
|
||
.. Note:: This guide is written for Python 3, however, these instructions
|
||
should work fine on Python 2.7—if you are still using it, for some reason.
|
||
|
||
|
||
☤ Make sure you've got Python & pip
|
||
===================================
|
||
|
||
Before you go any further, make sure you have Python and that it's available
|
||
from your command line. You can check this by simply running::
|
||
|
||
$ python --version
|
||
|
||
You should get some output like ``3.10.8``. 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 newcomer and you get an error like this:
|
||
|
||
.. code-block:: pycon
|
||
|
||
>>> python
|
||
Traceback (most recent call last):
|
||
File "<stdin>", line 1, in <module>
|
||
NameError: name 'python' is not defined
|
||
|
||
It's because this command is 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.
|
||
|
||
Additionally, you'll need to make sure you have pip available. You can
|
||
check this by running::
|
||
|
||
$ pip --version
|
||
pip 22.3.1
|
||
|
||
If you installed Python from source, with an installer from `python.org`_, via `Homebrew`_ or via `Linuxbrew`_ you should already have pip. If you're on Linux and installed
|
||
using your OS package manager, you may have to `install pip <https://pip.pypa.io/en/stable/installing/>`_ separately.
|
||
|
||
If you plan to install Pipenv using Homebrew or Linuxbrew you can skip this step. The
|
||
Homebrew/Linuxbrew installer takes care of pip for you.
|
||
|
||
.. _getting started tutorial: https://opentechschool.github.io/python-beginners/en/getting_started.html#what-is-python-exactly
|
||
.. _python.org: https://python.org
|
||
.. _Homebrew: https://brew.sh
|
||
.. _Linuxbrew: https://linuxbrew.sh/
|
||
.. _Installing Python: http://docs.python-guide.org/en/latest/starting/installation/
|
||
|
||
|
||
.. _installing-pipenv:
|
||
|
||
☤ Installing Pipenv
|
||
===================
|
||
|
||
It is recommended that users on most platforms should install pipenv from pypi.org using ``pip install pipenv``.
|
||
|
||
|
||
☤ Isolated Installation of Pipenv with Pipx
|
||
-------------------------------------------
|
||
|
||
`Pipx`_ is a tool to help you install and run end-user applications written in Python. It installs applications
|
||
into an isolated and clean environment on their own. To install pipx, just run::
|
||
|
||
$ pip install --user pipx
|
||
|
||
Once you have ``pipx`` ready on your system, continue to install Pipenv::
|
||
|
||
$ pipx install pipenv
|
||
|
||
.. _Pipx: https://pypa.github.io/pipx/
|
||
|
||
|
||
☤ Pragmatic Installation of Pipenv
|
||
----------------------------------
|
||
|
||
If you have a working installation of pip, and maintain certain "tool-chain" type Python modules as global utilities in your user environment, pip `user installs <https://pip.pypa.io/en/stable/user_guide/#user-installs>`_ allow for installation into your home directory. Note that due to interaction between dependencies, you should limit tools installed in this way to basic building blocks for a Python workflow like virtualenv, pipenv, tox, and similar software.
|
||
|
||
To install::
|
||
|
||
$ pip install --user pipenv
|
||
|
||
.. Note:: This does a `user installation`_ to prevent breaking any system-wide
|
||
packages. If ``pipenv`` isn't available in your shell after installation,
|
||
you'll need to add the `user base`_'s binary directory to your ``PATH``.
|
||
|
||
On Linux and macOS you can find the user base binary directory by running
|
||
``python -m site --user-base`` and adding ``bin`` to the end. For example,
|
||
this will typically print ``~/.local`` (with ``~`` expanded to the
|
||
absolute path to your home directory) so you'll need to add
|
||
``~/.local/bin`` to your ``PATH``. You can set your ``PATH`` permanently by
|
||
`modifying ~/.profile`_.
|
||
|
||
On Windows you can find the user base binary directory by running
|
||
``python -m site --user-site`` and replacing ``site-packages`` with
|
||
``Scripts``. For example, this could return
|
||
``C:\Users\Username\AppData\Roaming\Python36\site-packages`` so you would
|
||
need to set your ``PATH`` to include
|
||
``C:\Users\Username\AppData\Roaming\Python36\Scripts``. You can set your
|
||
user ``PATH`` permanently in the `Control Panel`_. You may need to log
|
||
out for the ``PATH`` changes to take effect.
|
||
|
||
For more information, see the `user installs documentation <https://pip.pypa.io/en/stable/user_guide/#user-installs>`_.
|
||
|
||
|
||
.. _user base: https://docs.python.org/3/library/site.html#site.USER_BASE
|
||
.. _user installation: https://pip.pypa.io/en/stable/user_guide/#user-installs
|
||
.. _modifying ~/.profile: https://stackoverflow.com/a/14638025
|
||
.. _Control Panel: https://msdn.microsoft.com/en-us/library/windows/desktop/bb776899(v=vs.85).aspx
|
||
|
||
|
||
To upgrade pipenv at any time::
|
||
|
||
$ pip install --user --upgrade pipenv
|
||
|
||
|
||
☤ Crude Installation of Pipenv
|
||
------------------------------
|
||
|
||
If you don't even have pip installed, you can use this crude installation method, which will bootstrap your whole system::
|
||
|
||
$ curl https://raw.githubusercontent.com/pypa/pipenv/master/get-pipenv.py | python
|
||
|
||
|
||
☤ Homebrew Installation of Pipenv(Discouraged)
|
||
----------------------------------------------
|
||
`Homebrew`_ is a popular open-source package management system for macOS. For Linux users, `Linuxbrew`_ is a Linux port of that.
|
||
|
||
Installing pipenv via Homebrew or Linuxbrew will keep pipenv and all of its dependencies in
|
||
an isolated virtual environment so it doesn't interfere with the rest of your
|
||
Python installation.
|
||
|
||
Once you have installed Homebrew or Linuxbrew simply run::
|
||
|
||
$ brew install pipenv
|
||
|
||
To upgrade pipenv at any time::
|
||
|
||
$ brew upgrade pipenv
|
||
|
||
.. Note::
|
||
Homebrew installation is discouraged because each time the Homebrew Python is upgraded, which Pipenv depends on,
|
||
users have to re-install Pipenv, and perhaps all virtual environments managed by it.
|
||
|
||
|
||
☤ Installing packages for your project
|
||
======================================
|
||
|
||
Pipenv manages dependencies on a per-project basis. To install packages,
|
||
change into your project's directory (or just an empty directory for this
|
||
tutorial) and run::
|
||
|
||
$ cd myproject
|
||
$ pipenv install requests
|
||
|
||
.. Note::
|
||
|
||
Pipenv is designed to be used by non-privileged OS users. It is not meant
|
||
to install or handle packages for the whole OS. Running Pipenv as ``root``
|
||
or with ``sudo`` (or ``Admin`` on Windows) is highly discouraged and might
|
||
lead to unintend breakage of your OS.
|
||
|
||
Pipenv will install the excellent `Requests`_ library and create a ``Pipfile``
|
||
for you in your project's directory. The ``Pipfile`` is used to track which
|
||
dependencies your project needs in case you need to re-install them, such as
|
||
when you share your project with others. You should get output similar to this
|
||
(although the exact paths shown will vary)::
|
||
|
||
pipenv install requests
|
||
Creating a virtualenv for this project...
|
||
Pipfile: /home/user/myproject/Pipfile
|
||
sing /home/user/.local/share/virtualenvs/pipenv-Cv0J3wbi/bin/python3.9 (3.9.9) to create virtualenv...
|
||
Creating virtual environment...created virtual environment CPython3.9.9.final.0-64 in 1142ms
|
||
creator CPython3Posix(dest=/home/user/.local/share/virtualenvs/myproject-R3jRVewK, clear=False, no_vcs_ignore=False, global=False)
|
||
seeder FromAppData(download=False, pip=bundle, setuptools=bundle, wheel=bundle, via=copy, app_data_dir=/home/user/.local/share/virtualenv)
|
||
added seed packages: pip==21.3.1, setuptools==60.2.0, wheel==0.37.1
|
||
activators BashActivator,CShellActivator,FishActivator,NushellActivator,PowerShellActivator,PythonActivator
|
||
|
||
✔ Successfully created virtual environment!
|
||
Virtualenv location: /home/user/.local/share/virtualenvs/pms-R3jRVewK
|
||
Creating a Pipfile for this project...
|
||
Installing requests...
|
||
Adding requests to Pipfile's [packages]...
|
||
Installation Succeeded
|
||
Pipfile.lock not found, creating...
|
||
Locking [dev-packages] dependencies...
|
||
Locking [packages] dependencies...
|
||
Building requirements...
|
||
Resolving dependencies...
|
||
✔ Success!
|
||
Updated Pipfile.lock (fe5a22)!
|
||
Installing dependencies from Pipfile.lock (fe5a22)...
|
||
🐍 ▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉▉ 0/0 — 00:00:00
|
||
|
||
.. _Requests: https://python-requests.org
|
||
|
||
|
||
☤ Using installed packages
|
||
==========================
|
||
|
||
Now that Requests is installed you can create a simple ``main.py`` file to
|
||
use it:
|
||
|
||
.. code-block:: python
|
||
|
||
import requests
|
||
|
||
response = requests.get('https://httpbin.org/ip')
|
||
|
||
print('Your IP is {0}'.format(response.json()['origin']))
|
||
|
||
Then you can run this script using ``pipenv run``::
|
||
|
||
$ pipenv run python main.py
|
||
|
||
You should get output similar to this:
|
||
|
||
.. code-block:: text
|
||
|
||
Your IP is 8.8.8.8
|
||
|
||
Using ``$ pipenv run`` ensures that your installed packages are available to
|
||
your script. It's also possible to spawn a new shell that ensures all commands
|
||
have access to your installed packages with ``$ pipenv shell``.
|
||
|
||
|
||
☤ Virtualenv mapping caveat
|
||
===========================
|
||
|
||
- Pipenv automatically maps projects to their specific virtualenvs.
|
||
- By default, the virtualenv is stored globally with the name of the project’s root directory plus the hash of the full path to the project's root (e.g., ``my_project-a3de50``).
|
||
- Should you change your project's path, you break such a default mapping and pipenv will no longer be able to find and to use the project's virtualenv.
|
||
- Customize this behavior with ``PIPENV_CUSTOM_VENV_NAME`` environment variable.
|
||
- You might also prefer to set ``PIPENV_VENV_IN_PROJECT=1`` in your .env or .bashrc/.zshrc (or other shell configuration file) for creating the virtualenv inside your project's directory.
|
||
|
||
|
||
☤ Next steps
|
||
============
|
||
|
||
Congratulations, you now know how to get started with pipenv, for additional details refer to the basic and advanced documentation. ✨ 🍰 ✨
|