File: //usr/share/doc/python3-django-q/html/install.html
<!DOCTYPE html>
<html class="writer-html5" lang="en" data-content_root="./">
<head>
<meta charset="utf-8" /><meta name="viewport" content="width=device-width, initial-scale=1" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<title>Installation — Django Q2 1.6.1 documentation</title>
<link rel="stylesheet" type="text/css" href="_static/pygments.css?v=b76e3c8a" />
<link rel="stylesheet" type="text/css" href="_static/css/theme.css?v=86f27845" />
<link rel="shortcut icon" href="_static/favicon.ico"/>
<script src="_static/jquery.js?v=8dae8fb0"></script>
<script src="_static/_sphinx_javascript_frameworks_compat.js?v=2cd50e6c"></script>
<script src="_static/documentation_options.js?v=d6a008b6"></script>
<script src="_static/doctools.js?v=888ff710"></script>
<script src="_static/sphinx_highlight.js?v=dc90522c"></script>
<script src="_static/js/theme.js"></script>
<link rel="index" title="Index" href="genindex.html" />
<link rel="search" title="Search" href="search.html" />
<link rel="next" title="Configuration" href="configure.html" />
<link rel="prev" title="Welcome to Django Q2" href="index.html" />
</head>
<body class="wy-body-for-nav">
<div class="wy-grid-for-nav">
<nav data-toggle="wy-nav-shift" class="wy-nav-side">
<div class="wy-side-scroll">
<div class="wy-side-nav-search" >
<a href="index.html" class="icon icon-home">
Django Q2
</a>
<div class="version">
1.6
</div>
<div role="search">
<form id="rtd-search-form" class="wy-form" action="search.html" method="get">
<input type="text" name="q" placeholder="Search docs" aria-label="Search docs" />
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
</div>
</div><div class="wy-menu wy-menu-vertical" data-spy="affix" role="navigation" aria-label="Navigation menu">
<ul class="current">
<li class="toctree-l1 current"><a class="current reference internal" href="#"> Installation</a><ul>
<li class="toctree-l2"><a class="reference internal" href="#migrate-from-django-q-to-django-q2">Migrate from Django-Q to Django-Q2</a></li>
<li class="toctree-l2"><a class="reference internal" href="#requirements">Requirements</a><ul>
<li class="toctree-l3"><a class="reference internal" href="#optional">Optional</a></li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="#add-ons">Add-ons</a><ul>
<li class="toctree-l3"><a class="reference internal" href="#os-x">OS X</a></li>
<li class="toctree-l3"><a class="reference internal" href="#windows">Windows</a></li>
<li class="toctree-l3"><a class="reference internal" href="#python">Python</a></li>
<li class="toctree-l3"><a class="reference internal" href="#open-source-packages">Open-source packages</a></li>
<li class="toctree-l3"><a class="reference internal" href="#django">Django</a></li>
</ul>
</li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="configure.html"> Configuration</a></li>
<li class="toctree-l1"><a class="reference internal" href="brokers.html"> Brokers</a></li>
<li class="toctree-l1"><a class="reference internal" href="tasks.html"> Tasks</a></li>
<li class="toctree-l1"><a class="reference internal" href="group.html"> Groups</a></li>
<li class="toctree-l1"><a class="reference internal" href="iterable.html"> Iterable</a></li>
<li class="toctree-l1"><a class="reference internal" href="chain.html"> Chains</a></li>
<li class="toctree-l1"><a class="reference internal" href="schedules.html"> Schedules</a></li>
<li class="toctree-l1"><a class="reference internal" href="cluster.html"> Cluster</a></li>
<li class="toctree-l1"><a class="reference internal" href="monitor.html"> Monitor</a></li>
<li class="toctree-l1"><a class="reference internal" href="admin.html"> Admin</a></li>
<li class="toctree-l1"><a class="reference internal" href="errors.html"> Errors</a></li>
<li class="toctree-l1"><a class="reference internal" href="signals.html"> Signals</a></li>
<li class="toctree-l1"><a class="reference internal" href="architecture.html"> Architecture</a></li>
<li class="toctree-l1"><a class="reference internal" href="examples.html"> Examples</a></li>
</ul>
</div>
</div>
</nav>
<section data-toggle="wy-nav-shift" class="wy-nav-content-wrap"><nav class="wy-nav-top" aria-label="Mobile navigation menu" >
<i data-toggle="wy-nav-top" class="fa fa-bars"></i>
<a href="index.html">Django Q2</a>
</nav>
<div class="wy-nav-content">
<div class="rst-content">
<div role="navigation" aria-label="Page navigation">
<ul class="wy-breadcrumbs">
<li><a href="index.html" class="icon icon-home" aria-label="Home"></a></li>
<li class="breadcrumb-item active">Installation</li>
<li class="wy-breadcrumbs-aside">
<a href="_sources/install.rst.txt" rel="nofollow"> View page source</a>
</li>
</ul>
<hr/>
</div>
<div role="main" class="document" itemscope="itemscope" itemtype="http://schema.org/Article">
<div itemprop="articleBody">
<section id="installation">
<h1>Installation<a class="headerlink" href="#installation" title="Link to this heading"></a></h1>
<ul>
<li><p>Install the latest version with pip:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>$ pip install django-q2
</pre></div>
</div>
</li>
<li><p>Add <a class="reference internal" href="configure.html#module-django_q" title="django_q"><code class="xref py py-mod docutils literal notranslate"><span class="pre">django_q</span></code></a> to <code class="docutils literal notranslate"><span class="pre">INSTALLED_APPS</span></code> in your projects <code class="file docutils literal notranslate"><span class="pre">settings.py</span></code>:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">INSTALLED_APPS</span> <span class="o">=</span> <span class="p">(</span>
<span class="c1"># other apps</span>
<span class="s1">'django_q'</span><span class="p">,</span>
<span class="p">)</span>
</pre></div>
</div>
</li>
<li><p>Run Django migrations to create the database tables:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>$ python manage.py migrate
</pre></div>
</div>
</li>
<li><p>Choose a message <a class="reference internal" href="brokers.html"><span class="doc">broker</span></a>, configure it and install the appropriate client library.</p></li>
<li><p>Run Django Q2 cluster in order to handle tasks async:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>$ python manage.py qcluster
</pre></div>
</div>
</li>
</ul>
<section id="migrate-from-django-q-to-django-q2">
<h2>Migrate from Django-Q to Django-Q2<a class="headerlink" href="#migrate-from-django-q-to-django-q2" title="Link to this heading"></a></h2>
<p>If you have an application with django-q running right now, you can simply swap the libraries and you should be good to go.:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>$ pip uninstall django-q # you might have to uninstall django-q add-ons as well
$ pip install django-q2
</pre></div>
</div>
<p>Then migrate the database to get the latest tables/fields:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>$ python manage.py migrate
</pre></div>
</div>
</section>
<section id="requirements">
<h2>Requirements<a class="headerlink" href="#requirements" title="Link to this heading"></a></h2>
<p>Django Q2 is tested for Python 3.8, 3.9, 3.10, 3.11 and 3.12</p>
<ul>
<li><p><a class="reference external" href="https://www.djangoproject.com">Django</a></p>
<blockquote>
<div><p>Django Q2 aims to use as much of Django’s standard offerings as possible.
The code is tested against Django versions <cite>3.2.x</cite>, <cite>4.1.x</cite>, <cite>4.2.x</cite> and <cite>5.0.x</cite>.</p>
</div></blockquote>
</li>
<li><p><a class="reference external" href="https://github.com/gintas/django-picklefield">Django-picklefield</a></p>
<blockquote>
<div><p>Used to store args, kwargs and result objects in the database.</p>
</div></blockquote>
</li>
</ul>
<section id="optional">
<h3>Optional<a class="headerlink" href="#optional" title="Link to this heading"></a></h3>
<ul>
<li><p><a class="reference external" href="https://github.com/jquast/blessed">Blessed</a> is used to display the statistics in the terminal:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>$ pip install blessed
</pre></div>
</div>
</li>
<li><p><a class="reference external" href="https://github.com/andymccurdy/redis-py">Redis-py</a> client by Andy McCurdy is used to interface with both the Redis:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>$ pip install redis
</pre></div>
</div>
</li>
</ul>
<ul id="psutil-package">
<li><p><a class="reference external" href="https://github.com/giampaolo/psutil">Psutil</a> python system and process utilities module by Giampaolo Rodola’, is an optional requirement and adds cpu affinity settings to the cluster:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>$ pip install psutil
</pre></div>
</div>
</li>
<li><p><a class="reference external" href="https://github.com/dvarrazzo/py-setproctitle">setproctitle</a> python module to customize the process title by Daniele Varrazzo’, is an optional requirement used to set informative process titles:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>$ pip install setproctitle
</pre></div>
</div>
</li>
<li><p><a class="reference external" href="https://github.com/redis/hiredis">Hiredis</a> parser. This C library maintained by the core Redis team is faster than the standard PythonParser during high loads:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>$ pip install hiredis
</pre></div>
</div>
</li>
<li><p><a class="reference external" href="https://github.com/boto/boto3">Boto3</a> is used for the Amazon SQS broker in favor of the now deprecating boto library:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>$ pip install boto3
</pre></div>
</div>
</li>
<li><p><a class="reference external" href="https://github.com/iron-io/iron_mq_python">Iron-mq</a> is the official python binding for the IronMQ broker:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>$ pip install iron-mq
</pre></div>
</div>
</li>
<li><p><a class="reference external" href="https://github.com/mongodb/mongo-python-driver">Pymongo</a> is needed if you want to use MongoDB as a message broker:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>$ pip install pymongo
</pre></div>
</div>
</li>
<li><p><a class="reference external" href="http://redis.io/">Redis</a> server is the default broker for Django Q2. It provides the best performance and does not require Django’s cache framework for monitoring.</p></li>
<li><p><a class="reference external" href="https://www.mongodb.org/">MongoDB</a> is a highly scalable NoSQL database which makes for a very fast and reliably persistent at-least-once message broker. Usually available on most PaaS providers.</p></li>
<li><p><a class="reference external" href="https://github.com/rollbar/pyrollbar">Pyrollbar</a> is an error notifier for <a class="reference external" href="https://rollbar.com/">Rollbar</a> which lets you manage your worker errors in one place. Needs a <a class="reference external" href="https://rollbar.com/">Rollbar</a> account and access key:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>$ pip install rollbar
</pre></div>
</div>
</li>
</ul>
<ul id="croniter-package">
<li><p><a class="reference external" href="https://github.com/kiorky/croniter">Croniter</a> is an optional package that is used to parse cron expressions for the scheduler:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>$ pip install croniter
</pre></div>
</div>
</li>
</ul>
</section>
</section>
<section id="add-ons">
<h2>Add-ons<a class="headerlink" href="#add-ons" title="Link to this heading"></a></h2>
<ul>
<li><p><a class="reference external" href="https://github.com/danielwelch/django-q-rollbar">django-q-rollbar</a> is a Rollbar error reporter:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>$ pip install django-q2[rollbar]
</pre></div>
</div>
</li>
<li><p><a class="reference external" href="https://github.com/danielwelch/django-q-sentry">django-q-sentry</a> is a Sentry error reporter:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>$ pip install django-q2[sentry]
</pre></div>
</div>
</li>
<li><p><a class="reference external" href="https://github.com/joeyespo/django-q-email">django-q-email</a> is a compatible Django email backend that will automatically async queue your emails.</p></li>
</ul>
<section id="os-x">
<h3>OS X<a class="headerlink" href="#os-x" title="Link to this heading"></a></h3>
<p>Running Django Q2 on OS X should work fine, except for the following known issues:</p>
<ul class="simple">
<li><p><code class="xref py py-meth docutils literal notranslate"><span class="pre">multiprocessing.Queue.qsize()</span></code> is not supported. This leads to the monitor not reporting the internal queue size of clusters running under OS X.</p></li>
<li><p>CPU count through <code class="xref py py-func docutils literal notranslate"><span class="pre">multiprocessing.cpu_count()</span></code> does not work. Installing <a class="reference internal" href="#psutil-package"><span class="std std-ref">psutil</span></a> provides Django Q2 with an alternative way of determining the number of CPU’s on your system</p></li>
<li><p>CPU affinity is provided by <a class="reference internal" href="#psutil-package"><span class="std std-ref">psutil</span></a> which at this time does not support this feature on OSX. The code however is aware of this and will fake the CPU affinity assignment in the logs without actually assigning it. This way you can still develop with this setting.</p></li>
</ul>
</section>
<section id="windows">
<h3>Windows<a class="headerlink" href="#windows" title="Link to this heading"></a></h3>
<p>The cluster and worker multiprocessing code depend on the OS’s ability to fork, unfortunately forking is not supported under windows.
You should however be able to develop and test without the cluster by setting the <code class="docutils literal notranslate"><span class="pre">sync</span></code> option to <code class="docutils literal notranslate"><span class="pre">True</span></code> in the configuration.
This will run all <code class="docutils literal notranslate"><span class="pre">async</span></code> calls inline through a single cluster worker without the need for forking.
Other known issues are:</p>
<ul class="simple">
<li><p><code class="xref py py-func docutils literal notranslate"><span class="pre">os.getppid()</span></code> is only supported under windows since Python 3.2. If you use an older version you need to install <a class="reference internal" href="#psutil-package"><span class="std std-ref">psutil</span></a> as an alternative.</p></li>
<li><p>CPU count through <code class="xref py py-func docutils literal notranslate"><span class="pre">multiprocessing.cpu_count()</span></code> occasionally fails on servers. Installing <a class="reference internal" href="#psutil-package"><span class="std std-ref">psutil</span></a> provides Django Q2 with an alternative way of determining the number of CPU’s on your system</p></li>
<li><p>The monitor and info commands rely on the Curses package which is not officially supported on windows. There are however some ports available like <a class="reference external" href="http://www.lfd.uci.edu/~gohlke/pythonlibs/#curses">this one</a> by Christoph Gohlke.</p></li>
</ul>
</section>
<section id="python">
<h3>Python<a class="headerlink" href="#python" title="Link to this heading"></a></h3>
<p>Current tests are performed with 3.8, 3.9, 3.10, 3.11 and 3.12
If you do encounter any regressions with earlier versions, please submit an issue on <a class="reference external" href="https://github.com/GDay/django-q2">github</a></p>
</section>
<section id="open-source-packages">
<h3>Open-source packages<a class="headerlink" href="#open-source-packages" title="Link to this heading"></a></h3>
<p>Django Q2 is always tested with the latest versions of the required and optional Python packages. We try to keep the dependencies as up to date as possible.
You can reference the <a class="reference external" href="https://github.com/GDay/django-q2/blob/master/requirements.txt">requirements</a> file to determine which versions are currently being used for tests and development.</p>
</section>
<section id="django">
<h3>Django<a class="headerlink" href="#django" title="Link to this heading"></a></h3>
<p>We strive to be compatible with the last two major version of Django.
At the moment this means we support the 3.2.x, 4.1.x, 4.2.x and 5.0.x releases.</p>
<p>Since we are now no longer supporting Python 2, we can also not support older versions of Django that do not support Python >= 3.8
For this you can always use older releases, but they are no longer maintained.</p>
</section>
</section>
</section>
</div>
</div>
<footer><div class="rst-footer-buttons" role="navigation" aria-label="Footer">
<a href="index.html" class="btn btn-neutral float-left" title="Welcome to Django Q2" accesskey="p" rel="prev"><span class="fa fa-arrow-circle-left" aria-hidden="true"></span> Previous</a>
<a href="configure.html" class="btn btn-neutral float-right" title="Configuration" accesskey="n" rel="next">Next <span class="fa fa-arrow-circle-right" aria-hidden="true"></span></a>
</div>
<hr/>
<div role="contentinfo">
<p>© Copyright 2015-2023, Ilan Steemers - 2022, Stan Triepels.</p>
</div>
Built with <a href="https://www.sphinx-doc.org/">Sphinx</a> using a
<a href="https://github.com/readthedocs/sphinx_rtd_theme">theme</a>
provided by <a href="https://readthedocs.org">Read the Docs</a>.
</footer>
</div>
</div>
</section>
</div>
<script>
jQuery(function () {
SphinxRtdTheme.Navigation.enable(true);
});
</script>
</body>
</html>