LocalSiteMap
LocalSiteMap is an open-source Python package designed for generating sitemaps and sitemap indexes from local files. It crawls your root website directory and automatically builds standard-compliant sitemaps. No third-party dependencies are required.
Changes in version 2.1.0
Breaking change
- Python 3.9 or newer is now required. Python 3.6 – 3.8 are long past end-of-life and are no longer supported by modern packaging tooling. Version
2.0.0on PyPI still serves those interpreters (pip selects it automatically), and the runtime code has no 3.9-only syntax.
Bug fixes
- Exclusions no longer match parent folders: exclusions are now resolved inside the site root, so a site checked out in (for example) a folder called
mediais not wiped out whenmediais excluded. - Priority map keys now behave as documented: folder keys may be written with a trailing slash (
"blog/"), Windows separators are accepted, and extension keys are matched case-insensitively (".PHP"matches.php). - URLs are percent-encoded: file and folder names containing spaces,
#,&,?or non-ASCII characters (e.g.my page.html,café/) now produce valid, crawlable URLs. - Extension matching is case-insensitive:
PAGE.HTMLis picked up by the default configuration, andpage.html.bakis not mistaken forpage.html. - Inputs are validated: a missing
root_path, abase_urlwithout a scheme, or a non-positivemax_urlsnow raise a clear error instead of silently writing a broken sitemap.max_urlsabove the protocol limit of 50 000 is clamped with a warning. - Priorities are clamped to the
0.00–1.00range required by the sitemap protocol. - Deterministic, deduplicated output: entries are sorted, duplicate
<loc>values are dropped, and repeated runs produce byte-identical files. - Stale split sitemaps are removed: shrinking a site no longer leaves orphaned
sitemap_N.xmlparts behind. - Output is written atomically and missing output directories are created, so an interrupted run cannot leave a truncated sitemap behind.
- Much faster XML writing: the DOM round-trip (
minidom) was replaced with a streaming writer, which also removes the stray blank lines from the output.
New features
- Command line interface:
localsitemap/python -m localsitemapwith exclusions, extensions, priorities and a JSON priority map. - Glob exclusions:
["draft-*", "*.bak"]. - New options:
exclude_hidden,include_homepage,sort_entries. generate_sitemap()returns the written files, which is handy for CI and build scripts.- Modern packaging: metadata moved to
pyproject.tomlwith the version read fromlocalsitemap/_version.py. - Release pipeline: published from GitHub Actions with PyPI Trusted Publishing (OIDC) and PEP 740 attestations — see Release provenance.
Changes in version 2.0.0 (Major Release)
- Precise Exclusions: Rewrote exclusion matching so only exact folder or filename matches (not partial substring matches) are excluded.
- Traversal Optimization: Subdirectories matching the exclusion list are pruned in-place, eliminating the overhead of traversing skipped directories.
- UTC Timestamps: Fixed timezone bug to retrieve and format all file modification timestamps as true, accurate UTC standard dates.
- Customizable File Extensions: Added optional
allowed_extensionsparameter to let you specify any list of file types to index (defaults to[".html", ".htm"]). - Flexible Priority Mappings: Custom mapping for directory/page priorities using a dictionary or callable mapping function.
- Sitemap Splitting & Sitemap Indexing: Automatically splits large sitemaps into chunks and creates a standard
<sitemapindex>parent if the URL limit (max_urls, defaults to 50,000) is exceeded.
Changes in version 1.0.2
- Removed the unnecessary
install_requiresfrom thesetup.pyas the package utilizes none of the required packages.
Changes in version 1.0.1
- Added
show_progressboolean to print out mapping progress, pages mapped, and files found.
Changes in version 1.0.0
- Added initial package code, with automatic directory crawling to generate the
sitemap.xmlfile.
Installation
You can install LocalSiteMap using pip:
pip install localsitemap
Supported Python Versions
LocalSiteMap supports Python 3.9 and newer, and every release is tested on CPython 3.9 – 3.14 on Linux, plus Windows:
- Python 3.9
- Python 3.10
- Python 3.11
- Python 3.12
- Python 3.13/Later (Preferred)
- Python 3.14
Features
- Directory Crawling:
LocalSiteMapautomatically crawls all subdirectories and files under the root directory, recursively adding them to your sitemap. - Optimized Walking: Excluded directories are completely skipped during traversal to ensure high performance even for large projects.
- UTC Last Modified Checks: Accurate file modification UTC timezone checks automatically update the
<lastmod>metadata tag. - Sitemap Splitting & Indexes: Automatically partitions large lists of pages/folders into multiple numbered sitemaps (e.g.
sitemap_1.xml,sitemap_2.xml) and outputs a compliantsitemap.xmlindex. - Customizable Extensions: Configure any extensions you want mapped instead of just standard HTML (e.g. php, pdf, txt).
- Flexible Priority Mapping: Map explicit paths to customized page weightings via custom definitions or callable filters.
- Open Source: Released under the terms of the Modified MIT License.
Usage
Generating a basic sitemap
from localsitemap import generate_sitemap
# Root site directory
root_directory = r"path/to/your/website/directory"
# Domain of your website (where it is hosted)
base_url_of_your_website = "https://example.com"
# Only exact folder names or complete relative paths will be skipped
excluded = ["auth", "forms", "template.html", "media", ".git", ".vscode", "node_modules"]
# Generate the sitemap
written = generate_sitemap(
root_directory,
base_url_of_your_website,
"sitemap.xml",
excluded,
show_progress=True,
)
print("Sitemap generated:", ", ".join(written))
Advanced Features (Extensions, Mappings & Splitting)
from localsitemap import generate_sitemap
# Custom priority dictionary or callable mapper.
# Keys may be a relative path, a folder name (trailing slash optional),
# a file name, or an extension (case-insensitive).
priority_mapping = {
"about/index.html": 0.95,
"blog/": 0.70,
".php": 0.50,
}
generate_sitemap(
root_path=r"path/to/website",
base_url="https://example.com",
output_file="sitemap.xml",
excluded_paths=["node_modules", ".git", "draft-*", "*.bak"],
allowed_extensions=[".html", ".htm", ".php"],
default_priority=0.80,
homepage_priority=1.00,
priority_mapping=priority_mapping,
max_urls=1000, # Automatically splits and writes a sitemap index above 1000 URLs
)
Exclusions
Exclusions are always interpreted relative to root_path:
| Pattern | Meaning |
|---|---|
"node_modules" |
any file or folder with that name, at any depth |
"blog/posts" |
that relative path and everything below it |
"/srv/site/private" |
an absolute path inside the site root |
"draft-*", "*.bak" |
shell-style glob patterns |
excluded_paths=["auth"] therefore excludes auth/ but keeps authority/.
Command line
# After pip install localsitemap (or with `python -m localsitemap`)
localsitemap path/to/website https://example.com \
-o public/sitemap.xml \
--exclude auth --exclude "draft-*" \
--extensions .html,.htm,.php \
--max-urls 1000 \
--progress
Run localsitemap --help for every option, including --priority-map priorities.json and --exclude-hidden.
Release provenance
Releases are built and published by GitHub Actions through PyPI Trusted Publishing (OIDC) — there is no long-lived PyPI API token in this repository. Every uploaded file is signed with a PEP 740 digital attestation, which is what makes PyPI display the provenance indicator for the release. You can verify it yourself with the bundled script:
python .github/scripts/verify_provenance.py --project localsitemap --version 2.1.0
or straight from the public Integrity API:
curl -s "https://pypi.org/integrity/localsitemap/2.1.0/localsitemap-2.1.0-py3-none-any.whl/provenance" \
| python -m json.tool
A non-404 response containing an attestation_bundles entry proves the file was built by this repository's workflow.
Contributing
Contributions are welcome! If you encounter any issues, have suggestions, or want to contribute to LocalSiteMap, please open an issue or submit a pull request on GitHub. See CONTRIBUTING.md for the test and release workflow.
License
LocalSiteMap is released under the terms of the MIT License (Modified). Please see the LICENSE file for the full text.
Modified License Clause
The modified license clause grants users the permission to make derivative works based on the LocalSiteMap software. However, it requires any substantial changes to the software to be clearly distinguished from the original work and distributed under a different name.
Metadata
Release files for localsitemap 2.1.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| localsitemap-2.1.0.tar.gz | 26.3 kB | With provenance | Details for localsitemap-2.1.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| localsitemap-2.1.0-py3-none-any.whl | Python 3 | none | any | Details for localsitemap-2.1.0-py3-none-any.whl |
Total release size: 42.3 kB
Release files / localsitemap-2.1.0.tar.gz
| Download URL | localsitemap-2.1.0.tar.gz |
|---|---|
| Size | 26.3 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
6197c099ca29c1790f826c70b69da0b0a427aa47885bb06aae7cd2ade8c3aff4
|
|
BLAKE2b-256 checksum How to use checksums |
7a5080bb4edfcc6ca9da7764ea174a0c183ed004240551771a9e27d9c1437f04
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 18, 2026.
Transparency logRelease files / localsitemap-2.1.0-py3-none-any.whl
| Download URL | localsitemap-2.1.0-py3-none-any.whl |
|---|---|
| Size | 15.9 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
ced19ca0b7a32ee59298c84ec73e081ec859995235e6d58524c783d1a69bb9bb
|
|
BLAKE2b-256 checksum How to use checksums |
d2f7c2702e174c37be42f830173608ba144993795813921a91ba76a43022c3cb
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 18, 2026.
Transparency logSecurity for localsitemap 2.1.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for localsitemap-2.1.0.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 18, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.