So you have decided to rename your package, but all your continuous integration, deployment to PyPi and/or conda-forge, and automatic documentation generation with readthedocs is already set up with the old name. The obvious fear is that everything will break and lead to a big ‘ol mess, but the process is actually easier than one might think if you follow these steps …

I learned this the hard way recently, when I went through the renaming of a package with - ahem - mixed emotions along the way.

Why tho?

Why would you want to rename your package in the first place? The short answer is: Don’t do it if you don not absolutely have to. More importantly, try to spend a bit more time to find a concise name when you create a repo, which might also coincidentally help you to refine the scope of your project. This is always a win-win in my eyes.

But maybe you still need to rename your package. Wether that is due to the fact that you inadvertently (I promise!) created a name that is NSFW or maybe the scope of your project did change.
Whatever the reason is there seems to be some interest) in the community how to go about this. And thankfully it really isn’t that hard to do.

Find a new name

Whether you have a brilliant name idea right away or go through a longer name search, the most important thing to do is to check that your new name is available on all the platforms you want to use it. In my example experience this was actually turned out to be the biggest pain in the rear. For the renaming of cmip6_preprocessing I initially wanted to use pyMIP but while this was available on Github, it turned out that someone published a PyPi package with that name without a connected Github name. We ended up with xMIP, and I quite like the name.

The biggest lesson I learned from this experience, is to check all the platforms you want to connect to the package:

• GitHub
• Pypi
• conda-forge
• any other platform that is linked in some way to your package (readthedocs, …)

Actually renaming the package

1. Backup all code locally in a separate location. You can never be too careful!
2. Rename your package on Github. Go to your repo page, and navigate to Settings > General and edit the Repository Name.
   Thats it on the Github side!
   Issues and Pull Requests are automatically migrated and the old url to your repo is automatically forwarded to the new one, which means you can keep your local repo as is and keep pushing from it, even though you might want to change the folder name and remotes just to keep things neat in the future.
3. Make a renaming PR to your repo. The easiest way to rename things is to do a global search and replace. I however recommend to check each renaming instance manually to avoid e.g. breaking links to the readthedocs documentation (more on that below). Dont forget to rename the module folder and run pre-commit locally (since the order of imports and other little things might change with different naming). This eventually should pass all of your CI.
4. Issue a test release on github to test if the automatic deployment to pypi (if you had that implemented in your repo like here for example). Before actually pulling the trigger, you should make sure that the token you use for pypi has global scope, rather than being restricted to your old namespace. Otherwise your deployment will inevitably break. You can replace the secrets with a new restricted token afterwards if you wish. Double check that your package was indeed released to pypi. Then we can take care of the conda-forge feedstock
5. The last required step is editing the recipe in the conda-forge feedstock. Note that you should NEVER rename the feedstock repo itself, or you will break the conda-forge bots. All you need to do is swap the package.name parameter in the meta.yaml.

Nice to haves

That is it with the basics. There are a few more things that might come in handy:

• Have a new logo ready (ideally insert it at step 3 above). Someone might shout out your work right away after you made the name change 🤗.
• Fix backward compatibility in PyPi. The basic idea is to release a ‘final’ version of your old name package manually that only contains your new package as a single dependency, so that users who do

  pip install old_name
  

  get the same package as folks who do

  pip install new_name
  

  There is also a cookiecutter that helps with the process. I still haven’t tried this, but will report back once done.

• Consider whether you want to rename the readthedocs namespace. This has some caveats though. If done all the old links to the documentation will break. Contrary to the renaming in Github, there is currently no good way to forward these urls automatically. If you decide to go this route, you have to actually email the readthedocs team to ask for a name change.

That’s it. Now enjoy your freshly renamed package!