mirror of
https://github.com/bunny-lab-io/Borealis.git
synced 2025-10-27 07:21:58 -06:00
663 lines
45 KiB
HTML
663 lines
45 KiB
HTML
<!DOCTYPE html>
|
||
|
||
<html lang="en" data-content_root="../">
|
||
<head>
|
||
<meta charset="utf-8" />
|
||
<meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="viewport" content="width=device-width, initial-scale=1" />
|
||
<meta property="og:title" content="An introduction to the ipaddress module" />
|
||
<meta property="og:type" content="website" />
|
||
<meta property="og:url" content="https://docs.python.org/3/howto/ipaddress.html" />
|
||
<meta property="og:site_name" content="Python documentation" />
|
||
<meta property="og:description" content="author, Peter Moody,, author, Nick Coghlan,. Overview: This document aims to provide a gentle introduction to the ipaddress module. It is aimed primarily at users that aren’t already familiar with ..." />
|
||
<meta property="og:image" content="https://docs.python.org/3/_static/og-image.png" />
|
||
<meta property="og:image:alt" content="Python documentation" />
|
||
<meta name="description" content="author, Peter Moody,, author, Nick Coghlan,. Overview: This document aims to provide a gentle introduction to the ipaddress module. It is aimed primarily at users that aren’t already familiar with ..." />
|
||
<meta property="og:image:width" content="200">
|
||
<meta property="og:image:height" content="200">
|
||
<meta name="theme-color" content="#3776ab">
|
||
|
||
<title>An introduction to the ipaddress module — Python 3.13.3 documentation</title><meta name="viewport" content="width=device-width, initial-scale=1.0">
|
||
|
||
<link rel="stylesheet" type="text/css" href="../_static/pygments.css?v=b86133f3" />
|
||
<link rel="stylesheet" type="text/css" href="../_static/pydoctheme.css?v=23252803" />
|
||
<link id="pygments_dark_css" media="(prefers-color-scheme: dark)" rel="stylesheet" type="text/css" href="../_static/pygments_dark.css?v=5349f25f" />
|
||
|
||
<script src="../_static/documentation_options.js?v=5d57ca2d"></script>
|
||
<script src="../_static/doctools.js?v=9bcbadda"></script>
|
||
<script src="../_static/sphinx_highlight.js?v=dc90522c"></script>
|
||
|
||
<script src="../_static/sidebar.js"></script>
|
||
|
||
<link rel="search" type="application/opensearchdescription+xml"
|
||
title="Search within Python 3.13.3 documentation"
|
||
href="../_static/opensearch.xml"/>
|
||
<link rel="author" title="About these documents" href="../about.html" />
|
||
<link rel="index" title="Index" href="../genindex.html" />
|
||
<link rel="search" title="Search" href="../search.html" />
|
||
<link rel="copyright" title="Copyright" href="../copyright.html" />
|
||
<link rel="next" title="Instrumenting CPython with DTrace and SystemTap" href="instrumentation.html" />
|
||
<link rel="prev" title="HOWTO Fetch Internet Resources Using The urllib Package" href="urllib2.html" />
|
||
|
||
<link rel="canonical" href="https://docs.python.org/3/howto/ipaddress.html">
|
||
|
||
|
||
|
||
|
||
|
||
<style>
|
||
@media only screen {
|
||
table.full-width-table {
|
||
width: 100%;
|
||
}
|
||
}
|
||
</style>
|
||
<link rel="stylesheet" href="../_static/pydoctheme_dark.css" media="(prefers-color-scheme: dark)" id="pydoctheme_dark_css">
|
||
<link rel="shortcut icon" type="image/png" href="../_static/py.svg" />
|
||
<script type="text/javascript" src="../_static/copybutton.js"></script>
|
||
<script type="text/javascript" src="../_static/menu.js"></script>
|
||
<script type="text/javascript" src="../_static/search-focus.js"></script>
|
||
<script type="text/javascript" src="../_static/themetoggle.js"></script>
|
||
<script type="text/javascript" src="../_static/rtd_switcher.js"></script>
|
||
<meta name="readthedocs-addons-api-version" content="1">
|
||
|
||
</head>
|
||
<body>
|
||
<div class="mobile-nav">
|
||
<input type="checkbox" id="menuToggler" class="toggler__input" aria-controls="navigation"
|
||
aria-pressed="false" aria-expanded="false" role="button" aria-label="Menu" />
|
||
<nav class="nav-content" role="navigation">
|
||
<label for="menuToggler" class="toggler__label">
|
||
<span></span>
|
||
</label>
|
||
<span class="nav-items-wrapper">
|
||
<a href="https://www.python.org/" class="nav-logo">
|
||
<img src="../_static/py.svg" alt="Python logo"/>
|
||
</a>
|
||
<span class="version_switcher_placeholder"></span>
|
||
<form role="search" class="search" action="../search.html" method="get">
|
||
<svg xmlns="http://www.w3.org/2000/svg" width="20" height="20" viewBox="0 0 24 24" class="search-icon">
|
||
<path fill-rule="nonzero" fill="currentColor" d="M15.5 14h-.79l-.28-.27a6.5 6.5 0 001.48-5.34c-.47-2.78-2.79-5-5.59-5.34a6.505 6.505 0 00-7.27 7.27c.34 2.8 2.56 5.12 5.34 5.59a6.5 6.5 0 005.34-1.48l.27.28v.79l4.25 4.25c.41.41 1.08.41 1.49 0 .41-.41.41-1.08 0-1.49L15.5 14zm-6 0C7.01 14 5 11.99 5 9.5S7.01 5 9.5 5 14 7.01 14 9.5 11.99 14 9.5 14z"></path>
|
||
</svg>
|
||
<input placeholder="Quick search" aria-label="Quick search" type="search" name="q" />
|
||
<input type="submit" value="Go"/>
|
||
</form>
|
||
</span>
|
||
</nav>
|
||
<div class="menu-wrapper">
|
||
<nav class="menu" role="navigation" aria-label="main navigation">
|
||
<div class="language_switcher_placeholder"></div>
|
||
|
||
<label class="theme-selector-label">
|
||
Theme
|
||
<select class="theme-selector" oninput="activateTheme(this.value)">
|
||
<option value="auto" selected>Auto</option>
|
||
<option value="light">Light</option>
|
||
<option value="dark">Dark</option>
|
||
</select>
|
||
</label>
|
||
<div>
|
||
<h3><a href="../contents.html">Table of Contents</a></h3>
|
||
<ul>
|
||
<li><a class="reference internal" href="#">An introduction to the ipaddress module</a><ul>
|
||
<li><a class="reference internal" href="#creating-address-network-interface-objects">Creating Address/Network/Interface objects</a><ul>
|
||
<li><a class="reference internal" href="#a-note-on-ip-versions">A Note on IP Versions</a></li>
|
||
<li><a class="reference internal" href="#ip-host-addresses">IP Host Addresses</a></li>
|
||
<li><a class="reference internal" href="#defining-networks">Defining Networks</a></li>
|
||
<li><a class="reference internal" href="#host-interfaces">Host Interfaces</a></li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="reference internal" href="#inspecting-address-network-interface-objects">Inspecting Address/Network/Interface Objects</a></li>
|
||
<li><a class="reference internal" href="#networks-as-lists-of-addresses">Networks as lists of Addresses</a></li>
|
||
<li><a class="reference internal" href="#comparisons">Comparisons</a></li>
|
||
<li><a class="reference internal" href="#using-ip-addresses-with-other-modules">Using IP Addresses with other modules</a></li>
|
||
<li><a class="reference internal" href="#getting-more-detail-when-instance-creation-fails">Getting more detail when instance creation fails</a></li>
|
||
</ul>
|
||
</li>
|
||
</ul>
|
||
|
||
</div>
|
||
<div>
|
||
<h4>Previous topic</h4>
|
||
<p class="topless"><a href="urllib2.html"
|
||
title="previous chapter">HOWTO Fetch Internet Resources Using The urllib Package</a></p>
|
||
</div>
|
||
<div>
|
||
<h4>Next topic</h4>
|
||
<p class="topless"><a href="instrumentation.html"
|
||
title="next chapter">Instrumenting CPython with DTrace and SystemTap</a></p>
|
||
</div>
|
||
<div role="note" aria-label="source link">
|
||
<h3>This Page</h3>
|
||
<ul class="this-page-menu">
|
||
<li><a href="../bugs.html">Report a Bug</a></li>
|
||
<li>
|
||
<a href="https://github.com/python/cpython/blob/main/Doc/howto/ipaddress.rst"
|
||
rel="nofollow">Show Source
|
||
</a>
|
||
</li>
|
||
</ul>
|
||
</div>
|
||
</nav>
|
||
</div>
|
||
</div>
|
||
|
||
|
||
<div class="related" role="navigation" aria-label="Related">
|
||
<h3>Navigation</h3>
|
||
<ul>
|
||
<li class="right" style="margin-right: 10px">
|
||
<a href="../genindex.html" title="General Index"
|
||
accesskey="I">index</a></li>
|
||
<li class="right" >
|
||
<a href="../py-modindex.html" title="Python Module Index"
|
||
>modules</a> |</li>
|
||
<li class="right" >
|
||
<a href="instrumentation.html" title="Instrumenting CPython with DTrace and SystemTap"
|
||
accesskey="N">next</a> |</li>
|
||
<li class="right" >
|
||
<a href="urllib2.html" title="HOWTO Fetch Internet Resources Using The urllib Package"
|
||
accesskey="P">previous</a> |</li>
|
||
|
||
<li><img src="../_static/py.svg" alt="Python logo" style="vertical-align: middle; margin-top: -1px"/></li>
|
||
<li><a href="https://www.python.org/">Python</a> »</li>
|
||
<li class="switchers">
|
||
<div class="language_switcher_placeholder"></div>
|
||
<div class="version_switcher_placeholder"></div>
|
||
</li>
|
||
<li>
|
||
|
||
</li>
|
||
<li id="cpython-language-and-version">
|
||
<a href="../index.html">3.13.3 Documentation</a> »
|
||
</li>
|
||
|
||
<li class="nav-item nav-item-1"><a href="index.html" accesskey="U">Python HOWTOs</a> »</li>
|
||
<li class="nav-item nav-item-this"><a href="">An introduction to the ipaddress module</a></li>
|
||
<li class="right">
|
||
|
||
|
||
<div class="inline-search" role="search">
|
||
<form class="inline-search" action="../search.html" method="get">
|
||
<input placeholder="Quick search" aria-label="Quick search" type="search" name="q" id="search-box" />
|
||
<input type="submit" value="Go" />
|
||
</form>
|
||
</div>
|
||
|
|
||
</li>
|
||
<li class="right">
|
||
<label class="theme-selector-label">
|
||
Theme
|
||
<select class="theme-selector" oninput="activateTheme(this.value)">
|
||
<option value="auto" selected>Auto</option>
|
||
<option value="light">Light</option>
|
||
<option value="dark">Dark</option>
|
||
</select>
|
||
</label> |</li>
|
||
|
||
</ul>
|
||
</div>
|
||
|
||
<div class="document">
|
||
<div class="documentwrapper">
|
||
<div class="bodywrapper">
|
||
<div class="body" role="main">
|
||
|
||
<section id="an-introduction-to-the-ipaddress-module">
|
||
<span id="ipaddress-howto"></span><h1>An introduction to the ipaddress module<a class="headerlink" href="#an-introduction-to-the-ipaddress-module" title="Link to this heading">¶</a></h1>
|
||
<dl class="field-list simple">
|
||
<dt class="field-odd">author<span class="colon">:</span></dt>
|
||
<dd class="field-odd"><p>Peter Moody</p>
|
||
</dd>
|
||
<dt class="field-even">author<span class="colon">:</span></dt>
|
||
<dd class="field-even"><p>Nick Coghlan</p>
|
||
</dd>
|
||
</dl>
|
||
<aside class="topic">
|
||
<p class="topic-title">Overview</p>
|
||
<p>This document aims to provide a gentle introduction to the
|
||
<a class="reference internal" href="../library/ipaddress.html#module-ipaddress" title="ipaddress: IPv4/IPv6 manipulation library."><code class="xref py py-mod docutils literal notranslate"><span class="pre">ipaddress</span></code></a> module. It is aimed primarily at users that aren’t
|
||
already familiar with IP networking terminology, but may also be useful
|
||
to network engineers wanting an overview of how <a class="reference internal" href="../library/ipaddress.html#module-ipaddress" title="ipaddress: IPv4/IPv6 manipulation library."><code class="xref py py-mod docutils literal notranslate"><span class="pre">ipaddress</span></code></a>
|
||
represents IP network addressing concepts.</p>
|
||
</aside>
|
||
<section id="creating-address-network-interface-objects">
|
||
<h2>Creating Address/Network/Interface objects<a class="headerlink" href="#creating-address-network-interface-objects" title="Link to this heading">¶</a></h2>
|
||
<p>Since <a class="reference internal" href="../library/ipaddress.html#module-ipaddress" title="ipaddress: IPv4/IPv6 manipulation library."><code class="xref py py-mod docutils literal notranslate"><span class="pre">ipaddress</span></code></a> is a module for inspecting and manipulating IP addresses,
|
||
the first thing you’ll want to do is create some objects. You can use
|
||
<a class="reference internal" href="../library/ipaddress.html#module-ipaddress" title="ipaddress: IPv4/IPv6 manipulation library."><code class="xref py py-mod docutils literal notranslate"><span class="pre">ipaddress</span></code></a> to create objects from strings and integers.</p>
|
||
<section id="a-note-on-ip-versions">
|
||
<h3>A Note on IP Versions<a class="headerlink" href="#a-note-on-ip-versions" title="Link to this heading">¶</a></h3>
|
||
<p>For readers that aren’t particularly familiar with IP addressing, it’s
|
||
important to know that the Internet Protocol (IP) is currently in the process
|
||
of moving from version 4 of the protocol to version 6. This transition is
|
||
occurring largely because version 4 of the protocol doesn’t provide enough
|
||
addresses to handle the needs of the whole world, especially given the
|
||
increasing number of devices with direct connections to the internet.</p>
|
||
<p>Explaining the details of the differences between the two versions of the
|
||
protocol is beyond the scope of this introduction, but readers need to at
|
||
least be aware that these two versions exist, and it will sometimes be
|
||
necessary to force the use of one version or the other.</p>
|
||
</section>
|
||
<section id="ip-host-addresses">
|
||
<h3>IP Host Addresses<a class="headerlink" href="#ip-host-addresses" title="Link to this heading">¶</a></h3>
|
||
<p>Addresses, often referred to as “host addresses” are the most basic unit
|
||
when working with IP addressing. The simplest way to create addresses is
|
||
to use the <a class="reference internal" href="../library/ipaddress.html#ipaddress.ip_address" title="ipaddress.ip_address"><code class="xref py py-func docutils literal notranslate"><span class="pre">ipaddress.ip_address()</span></code></a> factory function, which automatically
|
||
determines whether to create an IPv4 or IPv6 address based on the passed in
|
||
value:</p>
|
||
<div class="doctest highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="n">ipaddress</span><span class="o">.</span><span class="n">ip_address</span><span class="p">(</span><span class="s1">'192.0.2.1'</span><span class="p">)</span>
|
||
<span class="go">IPv4Address('192.0.2.1')</span>
|
||
<span class="gp">>>> </span><span class="n">ipaddress</span><span class="o">.</span><span class="n">ip_address</span><span class="p">(</span><span class="s1">'2001:DB8::1'</span><span class="p">)</span>
|
||
<span class="go">IPv6Address('2001:db8::1')</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>Addresses can also be created directly from integers. Values that will
|
||
fit within 32 bits are assumed to be IPv4 addresses:</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="n">ipaddress</span><span class="o">.</span><span class="n">ip_address</span><span class="p">(</span><span class="mi">3221225985</span><span class="p">)</span>
|
||
<span class="go">IPv4Address('192.0.2.1')</span>
|
||
<span class="gp">>>> </span><span class="n">ipaddress</span><span class="o">.</span><span class="n">ip_address</span><span class="p">(</span><span class="mi">42540766411282592856903984951653826561</span><span class="p">)</span>
|
||
<span class="go">IPv6Address('2001:db8::1')</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>To force the use of IPv4 or IPv6 addresses, the relevant classes can be
|
||
invoked directly. This is particularly useful to force creation of IPv6
|
||
addresses for small integers:</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="n">ipaddress</span><span class="o">.</span><span class="n">ip_address</span><span class="p">(</span><span class="mi">1</span><span class="p">)</span>
|
||
<span class="go">IPv4Address('0.0.0.1')</span>
|
||
<span class="gp">>>> </span><span class="n">ipaddress</span><span class="o">.</span><span class="n">IPv4Address</span><span class="p">(</span><span class="mi">1</span><span class="p">)</span>
|
||
<span class="go">IPv4Address('0.0.0.1')</span>
|
||
<span class="gp">>>> </span><span class="n">ipaddress</span><span class="o">.</span><span class="n">IPv6Address</span><span class="p">(</span><span class="mi">1</span><span class="p">)</span>
|
||
<span class="go">IPv6Address('::1')</span>
|
||
</pre></div>
|
||
</div>
|
||
</section>
|
||
<section id="defining-networks">
|
||
<h3>Defining Networks<a class="headerlink" href="#defining-networks" title="Link to this heading">¶</a></h3>
|
||
<p>Host addresses are usually grouped together into IP networks, so
|
||
<a class="reference internal" href="../library/ipaddress.html#module-ipaddress" title="ipaddress: IPv4/IPv6 manipulation library."><code class="xref py py-mod docutils literal notranslate"><span class="pre">ipaddress</span></code></a> provides a way to create, inspect and manipulate network
|
||
definitions. IP network objects are constructed from strings that define the
|
||
range of host addresses that are part of that network. The simplest form
|
||
for that information is a “network address/network prefix” pair, where the
|
||
prefix defines the number of leading bits that are compared to determine
|
||
whether or not an address is part of the network and the network address
|
||
defines the expected value of those bits.</p>
|
||
<p>As for addresses, a factory function is provided that determines the correct
|
||
IP version automatically:</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="n">ipaddress</span><span class="o">.</span><span class="n">ip_network</span><span class="p">(</span><span class="s1">'192.0.2.0/24'</span><span class="p">)</span>
|
||
<span class="go">IPv4Network('192.0.2.0/24')</span>
|
||
<span class="gp">>>> </span><span class="n">ipaddress</span><span class="o">.</span><span class="n">ip_network</span><span class="p">(</span><span class="s1">'2001:db8::0/96'</span><span class="p">)</span>
|
||
<span class="go">IPv6Network('2001:db8::/96')</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>Network objects cannot have any host bits set. The practical effect of this
|
||
is that <code class="docutils literal notranslate"><span class="pre">192.0.2.1/24</span></code> does not describe a network. Such definitions are
|
||
referred to as interface objects since the ip-on-a-network notation is
|
||
commonly used to describe network interfaces of a computer on a given network
|
||
and are described further in the next section.</p>
|
||
<p>By default, attempting to create a network object with host bits set will
|
||
result in <a class="reference internal" href="../library/exceptions.html#ValueError" title="ValueError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">ValueError</span></code></a> being raised. To request that the
|
||
additional bits instead be coerced to zero, the flag <code class="docutils literal notranslate"><span class="pre">strict=False</span></code> can
|
||
be passed to the constructor:</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="n">ipaddress</span><span class="o">.</span><span class="n">ip_network</span><span class="p">(</span><span class="s1">'192.0.2.1/24'</span><span class="p">)</span>
|
||
<span class="gt">Traceback (most recent call last):</span>
|
||
<span class="w"> </span><span class="c">...</span>
|
||
<span class="gr">ValueError</span>: <span class="n">192.0.2.1/24 has host bits set</span>
|
||
<span class="gp">>>> </span><span class="n">ipaddress</span><span class="o">.</span><span class="n">ip_network</span><span class="p">(</span><span class="s1">'192.0.2.1/24'</span><span class="p">,</span> <span class="n">strict</span><span class="o">=</span><span class="kc">False</span><span class="p">)</span>
|
||
<span class="go">IPv4Network('192.0.2.0/24')</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>While the string form offers significantly more flexibility, networks can
|
||
also be defined with integers, just like host addresses. In this case, the
|
||
network is considered to contain only the single address identified by the
|
||
integer, so the network prefix includes the entire network address:</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="n">ipaddress</span><span class="o">.</span><span class="n">ip_network</span><span class="p">(</span><span class="mi">3221225984</span><span class="p">)</span>
|
||
<span class="go">IPv4Network('192.0.2.0/32')</span>
|
||
<span class="gp">>>> </span><span class="n">ipaddress</span><span class="o">.</span><span class="n">ip_network</span><span class="p">(</span><span class="mi">42540766411282592856903984951653826560</span><span class="p">)</span>
|
||
<span class="go">IPv6Network('2001:db8::/128')</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>As with addresses, creation of a particular kind of network can be forced
|
||
by calling the class constructor directly instead of using the factory
|
||
function.</p>
|
||
</section>
|
||
<section id="host-interfaces">
|
||
<h3>Host Interfaces<a class="headerlink" href="#host-interfaces" title="Link to this heading">¶</a></h3>
|
||
<p>As mentioned just above, if you need to describe an address on a particular
|
||
network, neither the address nor the network classes are sufficient.
|
||
Notation like <code class="docutils literal notranslate"><span class="pre">192.0.2.1/24</span></code> is commonly used by network engineers and the
|
||
people who write tools for firewalls and routers as shorthand for “the host
|
||
<code class="docutils literal notranslate"><span class="pre">192.0.2.1</span></code> on the network <code class="docutils literal notranslate"><span class="pre">192.0.2.0/24</span></code>”, Accordingly, <a class="reference internal" href="../library/ipaddress.html#module-ipaddress" title="ipaddress: IPv4/IPv6 manipulation library."><code class="xref py py-mod docutils literal notranslate"><span class="pre">ipaddress</span></code></a>
|
||
provides a set of hybrid classes that associate an address with a particular
|
||
network. The interface for creation is identical to that for defining network
|
||
objects, except that the address portion isn’t constrained to being a network
|
||
address.</p>
|
||
<div class="doctest highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="n">ipaddress</span><span class="o">.</span><span class="n">ip_interface</span><span class="p">(</span><span class="s1">'192.0.2.1/24'</span><span class="p">)</span>
|
||
<span class="go">IPv4Interface('192.0.2.1/24')</span>
|
||
<span class="gp">>>> </span><span class="n">ipaddress</span><span class="o">.</span><span class="n">ip_interface</span><span class="p">(</span><span class="s1">'2001:db8::1/96'</span><span class="p">)</span>
|
||
<span class="go">IPv6Interface('2001:db8::1/96')</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>Integer inputs are accepted (as with networks), and use of a particular IP
|
||
version can be forced by calling the relevant constructor directly.</p>
|
||
</section>
|
||
</section>
|
||
<section id="inspecting-address-network-interface-objects">
|
||
<h2>Inspecting Address/Network/Interface Objects<a class="headerlink" href="#inspecting-address-network-interface-objects" title="Link to this heading">¶</a></h2>
|
||
<p>You’ve gone to the trouble of creating an IPv(4|6)(Address|Network|Interface)
|
||
object, so you probably want to get information about it. <a class="reference internal" href="../library/ipaddress.html#module-ipaddress" title="ipaddress: IPv4/IPv6 manipulation library."><code class="xref py py-mod docutils literal notranslate"><span class="pre">ipaddress</span></code></a>
|
||
tries to make doing this easy and intuitive.</p>
|
||
<p>Extracting the IP version:</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="n">addr4</span> <span class="o">=</span> <span class="n">ipaddress</span><span class="o">.</span><span class="n">ip_address</span><span class="p">(</span><span class="s1">'192.0.2.1'</span><span class="p">)</span>
|
||
<span class="gp">>>> </span><span class="n">addr6</span> <span class="o">=</span> <span class="n">ipaddress</span><span class="o">.</span><span class="n">ip_address</span><span class="p">(</span><span class="s1">'2001:db8::1'</span><span class="p">)</span>
|
||
<span class="gp">>>> </span><span class="n">addr6</span><span class="o">.</span><span class="n">version</span>
|
||
<span class="go">6</span>
|
||
<span class="gp">>>> </span><span class="n">addr4</span><span class="o">.</span><span class="n">version</span>
|
||
<span class="go">4</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>Obtaining the network from an interface:</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="n">host4</span> <span class="o">=</span> <span class="n">ipaddress</span><span class="o">.</span><span class="n">ip_interface</span><span class="p">(</span><span class="s1">'192.0.2.1/24'</span><span class="p">)</span>
|
||
<span class="gp">>>> </span><span class="n">host4</span><span class="o">.</span><span class="n">network</span>
|
||
<span class="go">IPv4Network('192.0.2.0/24')</span>
|
||
<span class="gp">>>> </span><span class="n">host6</span> <span class="o">=</span> <span class="n">ipaddress</span><span class="o">.</span><span class="n">ip_interface</span><span class="p">(</span><span class="s1">'2001:db8::1/96'</span><span class="p">)</span>
|
||
<span class="gp">>>> </span><span class="n">host6</span><span class="o">.</span><span class="n">network</span>
|
||
<span class="go">IPv6Network('2001:db8::/96')</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>Finding out how many individual addresses are in a network:</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="n">net4</span> <span class="o">=</span> <span class="n">ipaddress</span><span class="o">.</span><span class="n">ip_network</span><span class="p">(</span><span class="s1">'192.0.2.0/24'</span><span class="p">)</span>
|
||
<span class="gp">>>> </span><span class="n">net4</span><span class="o">.</span><span class="n">num_addresses</span>
|
||
<span class="go">256</span>
|
||
<span class="gp">>>> </span><span class="n">net6</span> <span class="o">=</span> <span class="n">ipaddress</span><span class="o">.</span><span class="n">ip_network</span><span class="p">(</span><span class="s1">'2001:db8::0/96'</span><span class="p">)</span>
|
||
<span class="gp">>>> </span><span class="n">net6</span><span class="o">.</span><span class="n">num_addresses</span>
|
||
<span class="go">4294967296</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>Iterating through the “usable” addresses on a network:</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="n">net4</span> <span class="o">=</span> <span class="n">ipaddress</span><span class="o">.</span><span class="n">ip_network</span><span class="p">(</span><span class="s1">'192.0.2.0/24'</span><span class="p">)</span>
|
||
<span class="gp">>>> </span><span class="k">for</span> <span class="n">x</span> <span class="ow">in</span> <span class="n">net4</span><span class="o">.</span><span class="n">hosts</span><span class="p">():</span>
|
||
<span class="gp">... </span> <span class="nb">print</span><span class="p">(</span><span class="n">x</span><span class="p">)</span>
|
||
<span class="go">192.0.2.1</span>
|
||
<span class="go">192.0.2.2</span>
|
||
<span class="go">192.0.2.3</span>
|
||
<span class="go">192.0.2.4</span>
|
||
<span class="go">...</span>
|
||
<span class="go">192.0.2.252</span>
|
||
<span class="go">192.0.2.253</span>
|
||
<span class="go">192.0.2.254</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>Obtaining the netmask (i.e. set bits corresponding to the network prefix) or
|
||
the hostmask (any bits that are not part of the netmask):</p>
|
||
<div class="doctest highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="n">net4</span> <span class="o">=</span> <span class="n">ipaddress</span><span class="o">.</span><span class="n">ip_network</span><span class="p">(</span><span class="s1">'192.0.2.0/24'</span><span class="p">)</span>
|
||
<span class="gp">>>> </span><span class="n">net4</span><span class="o">.</span><span class="n">netmask</span>
|
||
<span class="go">IPv4Address('255.255.255.0')</span>
|
||
<span class="gp">>>> </span><span class="n">net4</span><span class="o">.</span><span class="n">hostmask</span>
|
||
<span class="go">IPv4Address('0.0.0.255')</span>
|
||
<span class="gp">>>> </span><span class="n">net6</span> <span class="o">=</span> <span class="n">ipaddress</span><span class="o">.</span><span class="n">ip_network</span><span class="p">(</span><span class="s1">'2001:db8::0/96'</span><span class="p">)</span>
|
||
<span class="gp">>>> </span><span class="n">net6</span><span class="o">.</span><span class="n">netmask</span>
|
||
<span class="go">IPv6Address('ffff:ffff:ffff:ffff:ffff:ffff::')</span>
|
||
<span class="gp">>>> </span><span class="n">net6</span><span class="o">.</span><span class="n">hostmask</span>
|
||
<span class="go">IPv6Address('::ffff:ffff')</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>Exploding or compressing the address:</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="n">addr6</span><span class="o">.</span><span class="n">exploded</span>
|
||
<span class="go">'2001:0db8:0000:0000:0000:0000:0000:0001'</span>
|
||
<span class="gp">>>> </span><span class="n">addr6</span><span class="o">.</span><span class="n">compressed</span>
|
||
<span class="go">'2001:db8::1'</span>
|
||
<span class="gp">>>> </span><span class="n">net6</span><span class="o">.</span><span class="n">exploded</span>
|
||
<span class="go">'2001:0db8:0000:0000:0000:0000:0000:0000/96'</span>
|
||
<span class="gp">>>> </span><span class="n">net6</span><span class="o">.</span><span class="n">compressed</span>
|
||
<span class="go">'2001:db8::/96'</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>While IPv4 doesn’t support explosion or compression, the associated objects
|
||
still provide the relevant properties so that version neutral code can
|
||
easily ensure the most concise or most verbose form is used for IPv6
|
||
addresses while still correctly handling IPv4 addresses.</p>
|
||
</section>
|
||
<section id="networks-as-lists-of-addresses">
|
||
<h2>Networks as lists of Addresses<a class="headerlink" href="#networks-as-lists-of-addresses" title="Link to this heading">¶</a></h2>
|
||
<p>It’s sometimes useful to treat networks as lists. This means it is possible
|
||
to index them like this:</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="n">net4</span><span class="p">[</span><span class="mi">1</span><span class="p">]</span>
|
||
<span class="go">IPv4Address('192.0.2.1')</span>
|
||
<span class="gp">>>> </span><span class="n">net4</span><span class="p">[</span><span class="o">-</span><span class="mi">1</span><span class="p">]</span>
|
||
<span class="go">IPv4Address('192.0.2.255')</span>
|
||
<span class="gp">>>> </span><span class="n">net6</span><span class="p">[</span><span class="mi">1</span><span class="p">]</span>
|
||
<span class="go">IPv6Address('2001:db8::1')</span>
|
||
<span class="gp">>>> </span><span class="n">net6</span><span class="p">[</span><span class="o">-</span><span class="mi">1</span><span class="p">]</span>
|
||
<span class="go">IPv6Address('2001:db8::ffff:ffff')</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>It also means that network objects lend themselves to using the list
|
||
membership test syntax like this:</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="k">if</span> <span class="n">address</span> <span class="ow">in</span> <span class="n">network</span><span class="p">:</span>
|
||
<span class="c1"># do something</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>Containment testing is done efficiently based on the network prefix:</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="n">addr4</span> <span class="o">=</span> <span class="n">ipaddress</span><span class="o">.</span><span class="n">ip_address</span><span class="p">(</span><span class="s1">'192.0.2.1'</span><span class="p">)</span>
|
||
<span class="gp">>>> </span><span class="n">addr4</span> <span class="ow">in</span> <span class="n">ipaddress</span><span class="o">.</span><span class="n">ip_network</span><span class="p">(</span><span class="s1">'192.0.2.0/24'</span><span class="p">)</span>
|
||
<span class="go">True</span>
|
||
<span class="gp">>>> </span><span class="n">addr4</span> <span class="ow">in</span> <span class="n">ipaddress</span><span class="o">.</span><span class="n">ip_network</span><span class="p">(</span><span class="s1">'192.0.3.0/24'</span><span class="p">)</span>
|
||
<span class="go">False</span>
|
||
</pre></div>
|
||
</div>
|
||
</section>
|
||
<section id="comparisons">
|
||
<h2>Comparisons<a class="headerlink" href="#comparisons" title="Link to this heading">¶</a></h2>
|
||
<p><a class="reference internal" href="../library/ipaddress.html#module-ipaddress" title="ipaddress: IPv4/IPv6 manipulation library."><code class="xref py py-mod docutils literal notranslate"><span class="pre">ipaddress</span></code></a> provides some simple, hopefully intuitive ways to compare
|
||
objects, where it makes sense:</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="n">ipaddress</span><span class="o">.</span><span class="n">ip_address</span><span class="p">(</span><span class="s1">'192.0.2.1'</span><span class="p">)</span> <span class="o"><</span> <span class="n">ipaddress</span><span class="o">.</span><span class="n">ip_address</span><span class="p">(</span><span class="s1">'192.0.2.2'</span><span class="p">)</span>
|
||
<span class="go">True</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>A <a class="reference internal" href="../library/exceptions.html#TypeError" title="TypeError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">TypeError</span></code></a> exception is raised if you try to compare objects of
|
||
different versions or different types.</p>
|
||
</section>
|
||
<section id="using-ip-addresses-with-other-modules">
|
||
<h2>Using IP Addresses with other modules<a class="headerlink" href="#using-ip-addresses-with-other-modules" title="Link to this heading">¶</a></h2>
|
||
<p>Other modules that use IP addresses (such as <a class="reference internal" href="../library/socket.html#module-socket" title="socket: Low-level networking interface."><code class="xref py py-mod docutils literal notranslate"><span class="pre">socket</span></code></a>) usually won’t
|
||
accept objects from this module directly. Instead, they must be coerced to
|
||
an integer or string that the other module will accept:</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="n">addr4</span> <span class="o">=</span> <span class="n">ipaddress</span><span class="o">.</span><span class="n">ip_address</span><span class="p">(</span><span class="s1">'192.0.2.1'</span><span class="p">)</span>
|
||
<span class="gp">>>> </span><span class="nb">str</span><span class="p">(</span><span class="n">addr4</span><span class="p">)</span>
|
||
<span class="go">'192.0.2.1'</span>
|
||
<span class="gp">>>> </span><span class="nb">int</span><span class="p">(</span><span class="n">addr4</span><span class="p">)</span>
|
||
<span class="go">3221225985</span>
|
||
</pre></div>
|
||
</div>
|
||
</section>
|
||
<section id="getting-more-detail-when-instance-creation-fails">
|
||
<h2>Getting more detail when instance creation fails<a class="headerlink" href="#getting-more-detail-when-instance-creation-fails" title="Link to this heading">¶</a></h2>
|
||
<p>When creating address/network/interface objects using the version-agnostic
|
||
factory functions, any errors will be reported as <a class="reference internal" href="../library/exceptions.html#ValueError" title="ValueError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">ValueError</span></code></a> with
|
||
a generic error message that simply says the passed in value was not
|
||
recognized as an object of that type. The lack of a specific error is
|
||
because it’s necessary to know whether the value is <em>supposed</em> to be IPv4
|
||
or IPv6 in order to provide more detail on why it has been rejected.</p>
|
||
<p>To support use cases where it is useful to have access to this additional
|
||
detail, the individual class constructors actually raise the
|
||
<a class="reference internal" href="../library/exceptions.html#ValueError" title="ValueError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">ValueError</span></code></a> subclasses <a class="reference internal" href="../library/ipaddress.html#ipaddress.AddressValueError" title="ipaddress.AddressValueError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">ipaddress.AddressValueError</span></code></a> and
|
||
<a class="reference internal" href="../library/ipaddress.html#ipaddress.NetmaskValueError" title="ipaddress.NetmaskValueError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">ipaddress.NetmaskValueError</span></code></a> to indicate exactly which part of
|
||
the definition failed to parse correctly.</p>
|
||
<p>The error messages are significantly more detailed when using the
|
||
class constructors directly. For example:</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="n">ipaddress</span><span class="o">.</span><span class="n">ip_address</span><span class="p">(</span><span class="s2">"192.168.0.256"</span><span class="p">)</span>
|
||
<span class="gt">Traceback (most recent call last):</span>
|
||
<span class="w"> </span><span class="c">...</span>
|
||
<span class="gr">ValueError</span>: <span class="n">'192.168.0.256' does not appear to be an IPv4 or IPv6 address</span>
|
||
<span class="gp">>>> </span><span class="n">ipaddress</span><span class="o">.</span><span class="n">IPv4Address</span><span class="p">(</span><span class="s2">"192.168.0.256"</span><span class="p">)</span>
|
||
<span class="gt">Traceback (most recent call last):</span>
|
||
<span class="w"> </span><span class="c">...</span>
|
||
<span class="gr">ipaddress.AddressValueError</span>: <span class="n">Octet 256 (> 255) not permitted in '192.168.0.256'</span>
|
||
|
||
<span class="gp">>>> </span><span class="n">ipaddress</span><span class="o">.</span><span class="n">ip_network</span><span class="p">(</span><span class="s2">"192.168.0.1/64"</span><span class="p">)</span>
|
||
<span class="gt">Traceback (most recent call last):</span>
|
||
<span class="w"> </span><span class="c">...</span>
|
||
<span class="gr">ValueError</span>: <span class="n">'192.168.0.1/64' does not appear to be an IPv4 or IPv6 network</span>
|
||
<span class="gp">>>> </span><span class="n">ipaddress</span><span class="o">.</span><span class="n">IPv4Network</span><span class="p">(</span><span class="s2">"192.168.0.1/64"</span><span class="p">)</span>
|
||
<span class="gt">Traceback (most recent call last):</span>
|
||
<span class="w"> </span><span class="c">...</span>
|
||
<span class="gr">ipaddress.NetmaskValueError</span>: <span class="n">'64' is not a valid netmask</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>However, both of the module specific exceptions have <a class="reference internal" href="../library/exceptions.html#ValueError" title="ValueError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">ValueError</span></code></a> as their
|
||
parent class, so if you’re not concerned with the particular type of error,
|
||
you can still write code like the following:</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="k">try</span><span class="p">:</span>
|
||
<span class="n">network</span> <span class="o">=</span> <span class="n">ipaddress</span><span class="o">.</span><span class="n">IPv4Network</span><span class="p">(</span><span class="n">address</span><span class="p">)</span>
|
||
<span class="k">except</span> <span class="ne">ValueError</span><span class="p">:</span>
|
||
<span class="nb">print</span><span class="p">(</span><span class="s1">'address/netmask is invalid for IPv4:'</span><span class="p">,</span> <span class="n">address</span><span class="p">)</span>
|
||
</pre></div>
|
||
</div>
|
||
</section>
|
||
</section>
|
||
|
||
|
||
<div class="clearer"></div>
|
||
</div>
|
||
</div>
|
||
</div>
|
||
<div class="sphinxsidebar" role="navigation" aria-label="Main">
|
||
<div class="sphinxsidebarwrapper">
|
||
<div>
|
||
<h3><a href="../contents.html">Table of Contents</a></h3>
|
||
<ul>
|
||
<li><a class="reference internal" href="#">An introduction to the ipaddress module</a><ul>
|
||
<li><a class="reference internal" href="#creating-address-network-interface-objects">Creating Address/Network/Interface objects</a><ul>
|
||
<li><a class="reference internal" href="#a-note-on-ip-versions">A Note on IP Versions</a></li>
|
||
<li><a class="reference internal" href="#ip-host-addresses">IP Host Addresses</a></li>
|
||
<li><a class="reference internal" href="#defining-networks">Defining Networks</a></li>
|
||
<li><a class="reference internal" href="#host-interfaces">Host Interfaces</a></li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="reference internal" href="#inspecting-address-network-interface-objects">Inspecting Address/Network/Interface Objects</a></li>
|
||
<li><a class="reference internal" href="#networks-as-lists-of-addresses">Networks as lists of Addresses</a></li>
|
||
<li><a class="reference internal" href="#comparisons">Comparisons</a></li>
|
||
<li><a class="reference internal" href="#using-ip-addresses-with-other-modules">Using IP Addresses with other modules</a></li>
|
||
<li><a class="reference internal" href="#getting-more-detail-when-instance-creation-fails">Getting more detail when instance creation fails</a></li>
|
||
</ul>
|
||
</li>
|
||
</ul>
|
||
|
||
</div>
|
||
<div>
|
||
<h4>Previous topic</h4>
|
||
<p class="topless"><a href="urllib2.html"
|
||
title="previous chapter">HOWTO Fetch Internet Resources Using The urllib Package</a></p>
|
||
</div>
|
||
<div>
|
||
<h4>Next topic</h4>
|
||
<p class="topless"><a href="instrumentation.html"
|
||
title="next chapter">Instrumenting CPython with DTrace and SystemTap</a></p>
|
||
</div>
|
||
<div role="note" aria-label="source link">
|
||
<h3>This Page</h3>
|
||
<ul class="this-page-menu">
|
||
<li><a href="../bugs.html">Report a Bug</a></li>
|
||
<li>
|
||
<a href="https://github.com/python/cpython/blob/main/Doc/howto/ipaddress.rst"
|
||
rel="nofollow">Show Source
|
||
</a>
|
||
</li>
|
||
</ul>
|
||
</div>
|
||
</div>
|
||
<div id="sidebarbutton" title="Collapse sidebar">
|
||
<span>«</span>
|
||
</div>
|
||
|
||
</div>
|
||
<div class="clearer"></div>
|
||
</div>
|
||
<div class="related" role="navigation" aria-label="Related">
|
||
<h3>Navigation</h3>
|
||
<ul>
|
||
<li class="right" style="margin-right: 10px">
|
||
<a href="../genindex.html" title="General Index"
|
||
>index</a></li>
|
||
<li class="right" >
|
||
<a href="../py-modindex.html" title="Python Module Index"
|
||
>modules</a> |</li>
|
||
<li class="right" >
|
||
<a href="instrumentation.html" title="Instrumenting CPython with DTrace and SystemTap"
|
||
>next</a> |</li>
|
||
<li class="right" >
|
||
<a href="urllib2.html" title="HOWTO Fetch Internet Resources Using The urllib Package"
|
||
>previous</a> |</li>
|
||
|
||
<li><img src="../_static/py.svg" alt="Python logo" style="vertical-align: middle; margin-top: -1px"/></li>
|
||
<li><a href="https://www.python.org/">Python</a> »</li>
|
||
<li class="switchers">
|
||
<div class="language_switcher_placeholder"></div>
|
||
<div class="version_switcher_placeholder"></div>
|
||
</li>
|
||
<li>
|
||
|
||
</li>
|
||
<li id="cpython-language-and-version">
|
||
<a href="../index.html">3.13.3 Documentation</a> »
|
||
</li>
|
||
|
||
<li class="nav-item nav-item-1"><a href="index.html" >Python HOWTOs</a> »</li>
|
||
<li class="nav-item nav-item-this"><a href="">An introduction to the ipaddress module</a></li>
|
||
<li class="right">
|
||
|
||
|
||
<div class="inline-search" role="search">
|
||
<form class="inline-search" action="../search.html" method="get">
|
||
<input placeholder="Quick search" aria-label="Quick search" type="search" name="q" id="search-box" />
|
||
<input type="submit" value="Go" />
|
||
</form>
|
||
</div>
|
||
|
|
||
</li>
|
||
<li class="right">
|
||
<label class="theme-selector-label">
|
||
Theme
|
||
<select class="theme-selector" oninput="activateTheme(this.value)">
|
||
<option value="auto" selected>Auto</option>
|
||
<option value="light">Light</option>
|
||
<option value="dark">Dark</option>
|
||
</select>
|
||
</label> |</li>
|
||
|
||
</ul>
|
||
</div>
|
||
<div class="footer">
|
||
©
|
||
<a href="../copyright.html">
|
||
|
||
Copyright
|
||
|
||
</a>
|
||
2001-2025, Python Software Foundation.
|
||
<br />
|
||
This page is licensed under the Python Software Foundation License Version 2.
|
||
<br />
|
||
Examples, recipes, and other code in the documentation are additionally licensed under the Zero Clause BSD License.
|
||
<br />
|
||
|
||
See <a href="/license.html">History and License</a> for more information.<br />
|
||
|
||
|
||
<br />
|
||
|
||
The Python Software Foundation is a non-profit corporation.
|
||
<a href="https://www.python.org/psf/donations/">Please donate.</a>
|
||
<br />
|
||
<br />
|
||
Last updated on Apr 08, 2025 (14:33 UTC).
|
||
|
||
<a href="/bugs.html">Found a bug</a>?
|
||
|
||
<br />
|
||
|
||
Created using <a href="https://www.sphinx-doc.org/">Sphinx</a> 8.2.3.
|
||
</div>
|
||
|
||
</body>
|
||
</html> |