Skip to content
A random Python package every time.
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Type Name Latest commit message Commit time
Failed to load latest commit information.


License: MIT Build Status PyPI pyversions PyPI version Code style: black

"It is a riddle, wrapped in a mystery, inside an enigma."

-- Sir Winston Churchill

Mystery is a Python package that is instantiated as a different package every time you install it!

It was inspired by this episode of the wonderful podcast Python Bytes (which in turn talked about this article regarding pip dependencies).

Also, a shoutout to this project by hugovk that creates dumps of the top downloaded packages in PyPI every week. Without it's existence, being able to randomly choose a top package from PyPI would've been a lot less fun.


Use the package manager pip to install mystery.

pip install --no-cache-dir mystery

The reason the --no-cache-dir flag is used is the random package choice process. The dynamically created local instance of the mystery package is simply getting cached so without disabling the caching process the same chosen package will be used in the next reinstallation.


import mystery  # Who knows what's inside?

# `mystery` is now some random package!

mystery.__name__  # Quick cheat if you really are curious ;)

# Here for testing purposes only but go ahead:
mystery.__mystery_init_py__  # String path pointing to mystery's file.
mystery.__mystery_package_name__  # The mystery package's supposed name.

How does it work?

Mystery doesn't come with it's own (well actually it does but it's only for setuptools to work, and even this one is also autogenerated when I distribute the package!).

What happens behind the scenes is that a file is being dynamically generated when the package is built and installed. Mystery uses either the newest online dump of the top downloaded PyPI packages stored in this repository or (in case the repository was unreachable) the backup offline dump that comes with mystery's distribution.

After choosing a package, mystery's will create a lockfile in the temporary directory that will store the chosen package's name. The reason for that is that pip will actually run twice: first when building the package (build_py command) and again when actually installing the package (install command). The lockfile will hence be used after it's creation (first run of to get the chosen package's name out of it (so the install_requires parameter in the two calls to setuptools.setup() will be in sync) and will then be deleted.

Note that using a lockfile means that if for some reason the lockfile's state gets out of sync (perhaps the setup process is stopped right after the build phase created the lockfile but before the installation phase deleted it) the next attempts at installing mystery will also fail. You can fix that by manually deleting the lockfile from your filesystem (it's location is stored in this configuration file).

I ran import mystery but I'm getting an error. Why?

If your error is in the form of:

Internal error: ... The mystery package wasn't playing nice. Sorry!

That (hopefully) means that this package's PyPI name does not coorelate to their name under setuptools.setup(), so when mystery tries to import that same name (because again, it's done dynamically using the name registered in PyPI) it simply can't find a matching package and that lovely error message will pop up.

Some famous packages who won't work for this reason are scikit_learn, pyyaml and... A bunch of Google's stuff. Just reinstall mystery and have fun with a different package!



You can’t perform that action at this time.