Modernizing Virtualenvwrapper Maintenance

Source code hosting for virtualenvwrapper has moved to GitHub. We are making a few breaking changes as part of cleaning up and modernizing the code base (dropping python2 and ksh support, for example), and I hope to have a 6.x release out, soon.

Some History

When I originally wrote virtualenvwrapper, it wasn’t clear which, if any, of the new version control system hosting sites would become dominant. The Python community seemed to gravitate slightly towards Mercurial, and so I set up a few repositories on BitBucket. Over time, it became clear that git was preferred more than Mercurial, and so when BitBucket added git hosting support I eventually converted all of the repositories to use git.

In 2016, I put out a call for help maintaining virtualenvwrapper. I had kept the project going for more than 7 years by then, but wasn’t a very active user. Since then, Jason Myers has helped, but neither of us has much time and so the project has been largely stagnant. Recently, Brett Cannon has started a discussion about how py-launcher can discover the right python interpreter. Virtualenvwrapper came up, and the conversation spurred me to look at the state of things again with the idea that we might need to add a feature to support the work Brett is doing.


I reviewed the existing issue backlog and pull requests. A few PRs were easy enough to merge, but almost everything else was very old and would require more effort than I wanted to invest at the time. The test suite was a bit of a mess, mostly because it relied on some features of virtualenv that had been dropped (especially the --no-site-packages option).

I contacted Jason to suggest we set up move to GitHub, set up CI, and otherwise take some steps to see if we could make minimal maintenance effort possible. He agreed, so I spent some time over the last week or two handling most of the migration, with his review.

I quickly reviewed and then merged or closed all of the open pull requests on BitBucket. Most were closed without merging, with a comment encouraging submitting PRs to the new location. I did the same for the open issues. Most were old enough that they’re either things users will have worked around or given up on, or new enough that I hope a request to reopen the issue on GitHub won’t be too annoying.

I set up GitHub actions for running CI, and then fixed the test suite. I used that work as an opportunity to drop support for ksh, to avoid having to find a way to run that test job. I either rewrote or deleted the tests using --no-site-packages. I also dropped the toggleglobalsitepackages command, which relied on similar capabilities. (If someone relies on that and wants to rewrite it to work with modern virtualenv, please submit a PR.)

As I was fixing the tests, I noticed a few other improvements we could make, like updating the versions of Python listed in the Trove classifiers and fixing broken links in the documentation.

After I had the tests basically working, I set up rules to help manage the repository, particularly a rule to automatically merge PRs if they have a reviewer’s approval and all of the tests pass. That should make maintenance easier, since we don’t have to review the PR and then come back to it later to merge it manually.

What’s Next

I would like to produce a new release, soon. The current version is 4.8.4. We have some known breaking changes, so SemVer indicates we need to update the major version. A few years ago we had a 5.0 release that was badly broken, so we’ll be skipping that version and going to 6.0. There are a few remaining cleanup items to take care of before we will be ready for a release, including having the build work now that we’ve renamed the master branch to main.

Next, see Removing Bitrot From Virtualenvwrapper’s Packaging