1Install
2=======
3
4NetworkX requires Python 3.7, 3.8, or 3.9.  If you do not already
5have a Python environment configured on your computer, please see the
6instructions for installing the full `scientific Python stack
7<https://scipy.org/install.html>`_.
8
9Below we assume you have the default Python environment already configured on
10your computer and you intend to install ``networkx`` inside of it.  If you want
11to create and work with Python virtual environments, please follow instructions
12on `venv <https://docs.python.org/3/library/venv.html>`_ and `virtual
13environments <http://docs.python-guide.org/en/latest/dev/virtualenvs/>`_.
14
15First, make sure you have the latest version of ``pip`` (the Python package manager)
16installed. If you do not, refer to the `Pip documentation
17<https://pip.pypa.io/en/stable/installing/>`_ and install ``pip`` first.
18
19Install the released version
20----------------------------
21
22Install the current release of ``networkx`` with ``pip``::
23
24    $ pip install networkx[default]
25
26To upgrade to a newer release use the ``--upgrade`` flag::
27
28    $ pip install --upgrade networkx[default]
29
30If you do not have permission to install software systemwide, you can
31install into your user directory using the ``--user`` flag::
32
33    $ pip install --user networkx[default]
34
35If you do not want to install our dependencies (e.g., ``numpy``, ``scipy``, etc.),
36you can use::
37
38    $ pip install networkx
39
40This may be helpful if you are using PyPy or you are working on a project that
41only needs a limited subset of our functionality and you want to limit the
42number of dependencies.
43
44Alternatively, you can manually download ``networkx`` from
45`GitHub <https://github.com/networkx/networkx/releases>`_  or
46`PyPI <https://pypi.python.org/pypi/networkx>`_.
47To install one of these versions, unpack it and run the following from the
48top-level source directory using the Terminal::
49
50    $ pip install .[default]
51
52Install the development version
53-------------------------------
54
55If you have `Git <https://git-scm.com/>`_ installed on your system, it is also
56possible to install the development version of ``networkx``.
57
58Before installing the development version, you may need to uninstall the
59standard version of ``networkx`` using ``pip``::
60
61    $ pip uninstall networkx
62
63Then do::
64
65    $ git clone https://github.com/networkx/networkx.git
66    $ cd networkx
67    $ pip install -e .[default]
68
69The ``pip install -e .[default]`` command allows you to follow the development branch as
70it changes by creating links in the right places and installing the command
71line scripts to the appropriate locations.
72
73Then, if you want to update ``networkx`` at any time, in the same directory do::
74
75    $ git pull
76
77Extra packages
78--------------
79
80.. note::
81   Some optional packages (e.g., `gdal`) may require compiling
82   C or C++ code.  If you have difficulty installing these packages
83   with `pip`, please consult the homepages of those packages.
84
85The following extra packages provide additional functionality. See the
86files in the ``requirements/`` directory for information about specific
87version requirements.
88
89- `PyGraphviz <http://pygraphviz.github.io/>`_ and
90  `pydot <https://github.com/erocarrera/pydot>`_ provide graph drawing
91  and graph layout algorithms via `GraphViz <http://graphviz.org/>`_.
92- `PyYAML <http://pyyaml.org/>`_ provides YAML format reading and writing.
93- `gdal <http://www.gdal.org/>`_ provides shapefile format reading and writing.
94- `lxml <http://lxml.de/>`_ used for GraphML XML format.
95
96To install ``networkx`` and extra packages, do::
97
98    $ pip install networkx[default,extra]
99
100To explicitly install all optional packages, do::
101
102    $ pip install pygraphviz pydot pyyaml gdal lxml
103
104Or, install any optional package (e.g., ``pygraphviz``) individually::
105
106    $ pip install pygraphviz
107
108Testing
109-------
110
111NetworkX uses the Python ``pytest`` testing package.  You can learn more
112about pytest on their `homepage <https://pytest.org>`_.
113
114Test a source distribution
115^^^^^^^^^^^^^^^^^^^^^^^^^^
116
117You can test the complete package from the unpacked source directory with::
118
119    pytest networkx
120
121Test an installed package
122^^^^^^^^^^^^^^^^^^^^^^^^^
123
124From a shell command prompt you can test the installed package with::
125
126   pytest --pyargs networkx
127