wtf is python-versioneer?

wallrj/python-versioneer — explained in plain English

Analysis updated 2026-08-12 · repo last pushed 2014-05-23

PythonAudience · developerComplexity · 2/5DormantLicenseSetup · moderate

Mindmap

mindmap
  root((repo))
  What it does
    Auto version numbers
    Reads Git tags
    Detects unreleased changes
  How it works
    Dynamic check in dev
    Static version in packages
    No Git needed for users
  Use cases
    Tag a new release
    Debug from version info
    Embed in your own project
  Tech stack
    Python
    Git
  Audience
    Python developers
    Open source maintainers
  License
    Public domain
    No license conflicts

mindmap root((repo)) What it does Auto version numbers Reads Git tags Detects unreleased changes How it works Dynamic check in dev Static version in packages No Git needed for users Use cases Tag a new release Debug from version info Embed in your own project Tech stack Python Git Audience Python developers Open source maintainers License Public domain No license conflicts

Why would anyone build with this?

REASON 1

Automatically set your Python package's version number from a Git tag instead of editing files manually.

REASON 2

Identify exactly which revision and uncommitted changes a user is running when they report a bug.

REASON 3

Package your project for distribution with a static version number baked in so users do not need Git installed.

REASON 4

Embed version management code directly into your own project without worrying about license conflicts.

What's in the stack?

PythonGit

How it stacks up

	wallrj/python-versioneer	0verflowme/learnings	0verflowme/r2ai
Language	Python	Python	Python
Last pushed	2014-05-23	2022-06-18	2025-11-19
Maintenance	Dormant	Dormant	Quiet
Setup difficulty	moderate	easy	moderate
Complexity	2/5	1/5	3/5
Audience	developer	researcher	developer

Figures from each repo's GitHub metadata at analysis time.

How do you spin it up?

Difficulty · moderate Time to first run · 30min

Requires copying Versioneer files into your project and configuring setup.py to integrate with Git tags.

This is public domain software, so you can use, modify, and embed it freely in any project without any license restrictions.

Wtf does this do

Versioneer is a tool for Python developers that automatically manages version numbers for software projects. Instead of manually editing a version string every time you release an update, you just create a tag in your version control system (like Git). Versioneer handles the rest, eliminating the tedious and error-prone step of updating version numbers across your project files. When a developer is working directly with a project's source code, Versioneer asks the version control system for the current version at runtime. It can tell exactly where the code stands, even if it is between official releases. For example, it can report that the code is two revisions past version 0.7 and has uncommitted changes. When the project is packaged for distribution, the tool replaces this dynamic check with a static, pre-calculated version number. This means people who download the packaged software get the correct version without needing their own version control system. This tool is designed for Python developers who manage their code with Git and regularly distribute their projects. Imagine a developer preparing a new release. With Versioneer, they simply tag the code as version 1.0 in Git, then package and upload it. When users install the software, it can correctly identify itself as version 1.0. If a user reports a bug, the developer can ask them to check the version, which might reveal they are running an unreleased snapshot with uncommitted changes. One notable aspect of the project is its focus on extensibility. The tool is designed so that the code specific to each version control system is kept in separate directories. While it currently supports Git, this structure is intended to make it easier to add support for other version control systems in the future. The code is also released into the public domain, which makes it easy for developers to embed directly into their own projects without worrying about license conflicts.

Yoink these prompts

Prompt 1

Help me add Versioneer to my Python project so that my package version is automatically read from Git tags and I never have to manually edit version strings again.

Prompt 2

My user reported a bug and Versioneer shows they are running a version two commits past 0.7 with uncommitted changes. Help me understand what that means and how to guide them to a clean release.

Prompt 3

Walk me through how Versioneer switches between a dynamic runtime version check during development and a static baked-in version when I build a package for distribution.

Prompt 4

I want to embed Versioneer's code into my own Python project. Since it is public domain, what files do I need to copy and what configuration do I add to my setup.py?

Frequently asked questions