201 lines
6.5 KiB
ReStructuredText
201 lines
6.5 KiB
ReStructuredText
Installing / Upgrading
|
|
======================
|
|
.. highlight:: bash
|
|
|
|
**PyMongo** is in the `Python Package Index
|
|
<http://pypi.python.org/pypi/pymongo/>`_.
|
|
|
|
.. warning:: **Do not install the "bson" package from pypi.** PyMongo comes
|
|
with its own bson package; doing "pip install bson" or "easy_install bson"
|
|
installs a third-party package that is incompatible with PyMongo.
|
|
|
|
Installing with pip
|
|
-------------------
|
|
|
|
We recommend using `pip <http://pypi.python.org/pypi/pip>`_
|
|
to install pymongo on all platforms::
|
|
|
|
$ python3 -m pip install pymongo
|
|
|
|
To get a specific version of pymongo::
|
|
|
|
$ python3 -m pip install pymongo==3.5.1
|
|
|
|
To upgrade using pip::
|
|
|
|
$ python3 -m pip install --upgrade pymongo
|
|
|
|
Dependencies
|
|
------------
|
|
|
|
PyMongo supports CPython 3.7+ and PyPy3.7+.
|
|
|
|
Required dependencies:
|
|
|
|
Support for mongodb+srv:// URIs requires `dnspython
|
|
<https://pypi.python.org/pypi/dnspython>`_
|
|
|
|
|
|
Optional dependencies:
|
|
|
|
GSSAPI authentication requires `pykerberos
|
|
<https://pypi.python.org/pypi/pykerberos>`_ on Unix or `WinKerberos
|
|
<https://pypi.python.org/pypi/winkerberos>`_ on Windows. The correct
|
|
dependency can be installed automatically along with PyMongo::
|
|
|
|
$ python3 -m pip install "pymongo[gssapi]"
|
|
|
|
:ref:`MONGODB-AWS` authentication requires `pymongo-auth-aws
|
|
<https://pypi.org/project/pymongo-auth-aws/>`_::
|
|
|
|
$ python3 -m pip install "pymongo[aws]"
|
|
|
|
|
|
|
|
:ref:`OCSP` requires `PyOpenSSL
|
|
<https://pypi.org/project/pyOpenSSL/>`_, `requests
|
|
<https://pypi.org/project/requests/>`_ and `service_identity
|
|
<https://pypi.org/project/service_identity/>`_::
|
|
|
|
$ python3 -m pip install "pymongo[ocsp]"
|
|
|
|
Wire protocol compression with snappy requires `python-snappy
|
|
<https://pypi.org/project/python-snappy>`_::
|
|
|
|
$ python3 -m pip install "pymongo[snappy]"
|
|
|
|
Wire protocol compression with zstandard requires `zstandard
|
|
<https://pypi.org/project/zstandard>`_::
|
|
|
|
$ python3 -m pip install "pymongo[zstd]"
|
|
|
|
:ref:`Client-Side Field Level Encryption` requires `pymongocrypt
|
|
<https://pypi.org/project/pymongocrypt/>`_ and
|
|
`pymongo-auth-aws <https://pypi.org/project/pymongo-auth-aws/>`_::
|
|
|
|
$ python3 -m pip install "pymongo[encryption]"
|
|
|
|
You can install all dependencies automatically with the following
|
|
command::
|
|
|
|
$ python3 -m pip install "pymongo[gssapi,aws,ocsp,snappy,zstd,encryption]"
|
|
|
|
Installing from source
|
|
----------------------
|
|
|
|
If you'd rather install directly from the source (i.e. to stay on the
|
|
bleeding edge), install the C extension dependencies then check out the
|
|
latest source from GitHub and install the driver from the resulting tree::
|
|
|
|
$ git clone https://github.com/mongodb/mongo-python-driver.git pymongo
|
|
$ cd pymongo/
|
|
$ pip install .
|
|
|
|
Installing from source on Unix
|
|
..............................
|
|
|
|
To build the optional C extensions on Linux or another non-macOS Unix you must
|
|
have the GNU C compiler (gcc) installed. Depending on your flavor of Unix
|
|
(or Linux distribution) you may also need a python development package that
|
|
provides the necessary header files for your version of Python. The package
|
|
name may vary from distro to distro.
|
|
|
|
Debian and Ubuntu users should issue the following command::
|
|
|
|
$ sudo apt-get install build-essential python-dev
|
|
|
|
Users of Red Hat based distributions (RHEL, CentOS, Amazon Linux, Oracle Linux,
|
|
Fedora, etc.) should issue the following command::
|
|
|
|
$ sudo yum install gcc python-devel
|
|
|
|
Installing from source on macOS / OSX
|
|
.....................................
|
|
|
|
If you want to install PyMongo with C extensions from source you will need
|
|
the command line developer tools. On modern versions of macOS they can be
|
|
installed by running the following in Terminal (found in
|
|
/Applications/Utilities/)::
|
|
|
|
xcode-select --install
|
|
|
|
For older versions of OSX you may need Xcode. See the notes below for various
|
|
OSX and Xcode versions.
|
|
|
|
**Snow Leopard (10.6)** - Xcode 3 with 'UNIX Development Support'.
|
|
|
|
**Snow Leopard Xcode 4**: The Python versions shipped with OSX 10.6.x
|
|
are universal binaries. They support i386, PPC, and x86_64. Xcode 4 removed
|
|
support for PPC, causing the distutils version shipped with Apple's builds of
|
|
Python to fail to build the C extensions if you have Xcode 4 installed. There
|
|
is a workaround::
|
|
|
|
# For some Python builds from python.org
|
|
$ env ARCHFLAGS='-arch i386 -arch x86_64' python -m easy_install pymongo
|
|
|
|
See `http://bugs.python.org/issue11623 <http://bugs.python.org/issue11623>`_
|
|
for a more detailed explanation.
|
|
|
|
**Lion (10.7) and newer** - PyMongo's C extensions can be built against
|
|
versions of Python 3.7+ downloaded from python.org. In all cases Xcode must be
|
|
installed with 'UNIX Development Support'.
|
|
|
|
**Xcode 5.1**: Starting with version 5.1 the version of clang that ships with
|
|
Xcode throws an error when it encounters compiler flags it doesn't recognize.
|
|
This may cause C extension builds to fail with an error similar to::
|
|
|
|
clang: error: unknown argument: '-mno-fused-madd' [-Wunused-command-line-argument-hard-error-in-future]
|
|
|
|
There are workarounds::
|
|
|
|
# Apple specified workaround for Xcode 5.1
|
|
# easy_install
|
|
$ ARCHFLAGS=-Wno-error=unused-command-line-argument-hard-error-in-future easy_install pymongo
|
|
# or pip
|
|
$ ARCHFLAGS=-Wno-error=unused-command-line-argument-hard-error-in-future pip install pymongo
|
|
|
|
# Alternative workaround using CFLAGS
|
|
# easy_install
|
|
$ CFLAGS=-Qunused-arguments easy_install pymongo
|
|
# or pip
|
|
$ CFLAGS=-Qunused-arguments pip install pymongo
|
|
|
|
|
|
Installing from source on Windows
|
|
.................................
|
|
|
|
If you want to install PyMongo with C extensions from source the following
|
|
requirements apply to both CPython and ActiveState's ActivePython:
|
|
|
|
Windows
|
|
~~~~~~~
|
|
|
|
Install Visual Studio 2015+.
|
|
|
|
.. _install-no-c:
|
|
|
|
Installing Without C Extensions
|
|
-------------------------------
|
|
|
|
By default, the driver attempts to build and install optional C
|
|
extensions (used for increasing performance) when it is installed. If
|
|
any extension fails to build the driver will be installed anyway but a
|
|
warning will be printed.
|
|
|
|
If you wish to install PyMongo without the C extensions, even if the
|
|
extensions build properly, it can be done using a command line option to
|
|
*setup.py*::
|
|
|
|
$ NO_EXT=1 python -m pip install .
|
|
|
|
Installing a beta or release candidate
|
|
--------------------------------------
|
|
|
|
MongoDB, Inc. may occasionally tag a beta or release candidate for testing by
|
|
the community before final release. These releases will not be uploaded to pypi
|
|
but can be found on the
|
|
`GitHub tags page <https://github.com/mongodb/mongo-python-driver/tags>`_.
|
|
They can be installed by passing the full URL for the tag to pip::
|
|
|
|
$ python3 -m pip install https://github.com/mongodb/mongo-python-driver/archive/4.4.0b0.tar.gz
|