Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Update quickstart guide to reflect user research #9137

Closed
wants to merge 5 commits into from
Closed
Changes from 2 commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
119 changes: 80 additions & 39 deletions docs/html/quickstart.rst
Original file line number Diff line number Diff line change
Expand Up @@ -2,90 +2,126 @@
Quickstart
==========

First, :doc:`install pip <installing>`.
pip is a command line tool for installing Python packages.

Install a package from `PyPI`_:
For a full tutorial on installing packages with pip, see the
`Python Packaging User Guide`_
nlhkabu marked this conversation as resolved.
Show resolved Hide resolved

For a more detailed exploration of pip's functionality see the pip
nlhkabu marked this conversation as resolved.
Show resolved Hide resolved
:doc:`user guide <user_guide>`.

Quick setup
===========
nlhkabu marked this conversation as resolved.
Show resolved Hide resolved

1. Check pip installation
-------------------------
Check if you already have pip installed by running:

.. code-block:: console

pip --version

See :doc:`installing pip <installing>` for more information, or to troubleshoot
any problems.

2. Check pip is up to date
--------------------------

To make sure you are running pip's latest version, run:

.. tab:: Unix/macOS

.. code-block:: console

$ python -m pip install SomePackage
[...]
Successfully installed SomePackage
python -m pip install -U pip

.. tab:: Windows

.. code-block:: console

C:\> py -m pip install SomePackage
[...]
Successfully installed SomePackage
py -m pip install -U pip


3. Set up a virtual environment
-------------------------------

Install a package that's already been downloaded from `PyPI`_ or
obtained from elsewhere. This is useful if the target machine does not have a
network connection:
Before using pip, we recommend you set up and use a virtual environment to
isolate your project packages.

See `Creating Virtual Environments`_ for more information.

Common tasks
============

Install a package from `PyPI`_
------------------------------

.. tab:: Unix/macOS

.. code-block:: console

$ python -m pip install SomePackage-1.0-py2.py3-none-any.whl
$ python -m pip install SomePackage
[...]
Successfully installed SomePackage

.. tab:: Windows

.. code-block:: console

C:\> py -m pip install SomePackage-1.0-py2.py3-none-any.whl
C:\> py -m pip install SomePackage
[...]
Successfully installed SomePackage

Show what files were installed:
Install a package from GitHub
------------------------------

.. tab:: Unix/macOS
Pip can install packages from common version control systems (VCS), including
GitHub.

.. code-block:: console
For example, to install a specific commit from the Django project, run:

$ python -m pip show --files SomePackage
Name: SomePackage
Version: 1.0
Location: /my/env/lib/pythonx.x/site-packages
Files:
../somepackage/__init__.py
[...]
.. code-block:: console

.. tab:: Windows
pip install git+https://github.com/django/django.git@45dfb3641aa4d9828a7c5448d11aa67c7cbd7966

.. code-block:: console
See VCS support for more information.
nlhkabu marked this conversation as resolved.
Show resolved Hide resolved

C:\> py -m pip show --files SomePackage
Name: SomePackage
Version: 1.0
Location: /my/env/lib/pythonx.x/site-packages
Files:
../somepackage/__init__.py
[...]
Install a package you have already downloaded
---------------------------------------------

List what packages are outdated:
This is useful if the target machine does not have a network connection:

.. tab:: Unix/macOS

.. code-block:: console

$ python -m pip list --outdated
SomePackage (Current: 1.0 Latest: 2.0)
$ python -m pip install SomePackage-1.0-py2.py3-none-any.whl
[...]
Successfully installed SomePackage

.. tab:: Windows

.. code-block:: console

C:\> py -m pip list --outdated
SomePackage (Current: 1.0 Latest: 2.0)
C:\> py -m pip install SomePackage-1.0-py2.py3-none-any.whl
[...]
Successfully installed SomePackage

Install packages from a file
----------------------------

Upgrade a package:
Many Python projects use a requirements.txt file to specify the list of packages
that need to be installed for the project to run. To install the packages
listed in the file, run:

.. code-block:: console

pip install -r requirements.txt

See requirements files for more information.
nlhkabu marked this conversation as resolved.
Show resolved Hide resolved

Upgrade a package
-----------------

.. tab:: Unix/macOS

Expand All @@ -111,7 +147,8 @@ Upgrade a package:
Running setup.py install for SomePackage
Successfully installed SomePackage

Uninstall a package:
Uninstall a package
-------------------

.. tab:: Unix/macOS

Expand All @@ -133,4 +170,8 @@ Uninstall a package:
Proceed (y/n)? y
Successfully uninstalled SomePackage

For a full list of pip commands, see the pip :doc:`reference guide <reference>`.
nlhkabu marked this conversation as resolved.
Show resolved Hide resolved

.. _PyPI: https://pypi.org/
.. _Python Packaging User Guide: https://packaging.python.org/tutorials/installing-packages
.. _Creating Virtual Environments: https://packaging.python.org/tutorials/installing-packages/#creating-virtual-environments