https://readthedocs-about--394.org.readthedocs.build/2026-04-21T00:00:00-07:002026-04-21T00:00:00-07:002026-04-21T00:00:00-07:00Manuel Kaufmantag:readthedocs-about--394.org.readthedocs.build,2026-04-21:/blog/2026/04/deprecate-setuptools-install/

<p>We are announcing the deprecation of <code>python.install.method: setuptools</code> in the <code>.readthedocs.yaml</code> configuration file.</p> <p>This option uses <code>python …</code></p>

<p>We are announcing the deprecation of <code>python.install.method: setuptools</code> in the <code>.readthedocs.yaml</code> configuration file.</p> <p>This option uses <code>python setup.py install</code>, which is deprecated in the Python packaging ecosystem. Read the Docs will remove support for it on <strong>Wednesday, July 1st, 2026</strong>. After this date, projects still using <code>python.install.method: setuptools</code> will fail their builds until they are updated.</p> <p>Projects using this install method will have a configuration file that looks like this:</p> <div class="highlight"><pre><span></span><code><span class="nt">version</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">2</span> <span class="nt">python</span><span class="p">:</span> <span class="w"> </span><span class="nt">install</span><span class="p">:</span> <span class="w"> </span><span class="p p-Indicator">-</span><span class="w"> </span><span class="nt">method</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">setuptools</span> <span class="w"> </span><span class="nt">path</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">.</span> </code></pre></div> <p>These projects should update their configuration file to use <code>pip</code> instead:</p> <div class="highlight"><pre><span></span><code><span class="nt">version</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">2</span> <span class="nt">python</span><span class="p">:</span> <span class="w"> </span><span class="nt">install</span><span class="p">:</span> <span class="w"> </span><span class="p p-Indicator">-</span><span class="w"> </span><span class="nt">method</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">pip</span> <span class="w"> </span><span class="nt">path</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">.</span> </code></pre></div> <p>If you are already using <code>python.install.method: pip</code>, <code>python.install.method: uv</code>, or you are not using <code>method: setuptools</code>, no action is required.</p> <p><code>pip</code> is the recommended replacement for most projects. If you are using <code>uv</code> for your Python dependency management, you can also migrate to <code>python.install.method: uv</code>.</p> <h2 id="deprecation-timeline">Deprecation timeline</h2> <ul> <li><strong>Tuesday, April 21, 2026</strong>: Publish this deprecation announcement.</li> <li><strong>Before Wednesday, July 1, 2026</strong>: Email maintainers of active projects that are still using <code>python.install.method: setuptools</code>.</li> <li><strong>Wednesday, July 1, 2026</strong>: Remove support for <code>python.install.method: setuptools</code> on Read the Docs.</li> </ul> <h2 id="how-to-update-your-project">How to update your project</h2> <p>For most projects, replacing <code>method: setuptools</code> with <code>method: pip</code> is enough. This changes the installation step from <code>python setup.py install</code> to <code>pip install</code>, which is the supported and recommended workflow.</p> <p>If your project installs optional dependencies, you can keep using <code>extra_requirements</code> with <code>pip</code>:</p> <div class="highlight"><pre><span></span><code><span class="nt">version</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">2</span> <span class="nt">python</span><span class="p">:</span> <span class="w"> </span><span class="nt">install</span><span class="p">:</span> <span class="w"> </span><span class="p p-Indicator">-</span><span class="w"> </span><span class="nt">method</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">pip</span> <span class="w"> </span><span class="nt">path</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">.</span> <span class="w"> </span><span class="nt">extra_requirements</span><span class="p">:</span> <span class="w"> </span><span class="p p-Indicator">-</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">docs</span> </code></pre></div> <p>Projects that only install requirements files and do not use <code>python.install.method: setuptools</code> are not affected by this change.</p> <h2 id="contact-us">Contact us</h2> <p><a href="https://app.readthedocs.org/support/">Contact us</a> if you have any questions, or if you run into issues migrating away from <code>python.install.method: setuptools</code>.</p>