PyCharm + Docker Compose: Couldn’t refresh skeletons for remote interpreter

Aron Schüler Published

If you see Couldn't refresh skeletons for remote interpreter, in your PyCharm event log, you don’t suspect a problem with docker-compose. But the real cause is the migration of docker-compose into docker compose. The error will be something like:

Couldn't refresh skeletons for remote interpreter
failed to run generator3/ for docker-compose://[/home/[...]/docker-compose.yml]:backend/python, exit code 1, stderr:

Now you will go ahead and google. But all you find are old threads pointing to permission errors for .state.json files or some other workarounds. However, these fixes are not permanent! PyCharm regenerates these stubs once you change or reopen your project. To fix it, you need to downgrade from docker-compose >= 2.

Downgrading to docker-compose v1

We can downgrade in two ways:

  1. By deactivating the link to v2. It might not work though, as Arch Linux has already removed the real docker-compose.
  2. Replacing your binary with a downgraded version, which will definitely work.

Version 1: Deactivate Compose v2 over docker-compose

docker-compose deactivate-v2

Boom! Fixed.

Or not?

If you just see a docker compose deactivate-v2 command not found, here's our help screen you don’t have the “real” docker-compose binary and cannot go back. You need to remove the script that replaced docker-compose and install the old binary again.

Version 2: Downgrading your binary

The second possible solution to this is installing an older docker-compose version. This is also still recommend in the official docker compose installation guide. To do so, you have to:

  1. Remove the link to the script
  2. Download the latest docker-compose binary
  3. Make it executable
  4. Link from the removed binary to the installed binary

This is done by the following commands:

sudo rm /usr/bin/docker-compose
sudo curl -L$(uname -s)-$(uname -m)" -o /usr/local/bin/docker-compose
sudo chmod +x /usr/local/bin/docker-compose
sudo ln -s /usr/local/bin/docker-compose /usr/bin/docker-compose


The docker-compose binary now provides all expected functionality to the remote interpreter of PyCharm again. If you’re just happy that you can debug with PyCharm again – go on with work then, have fun! If you want to know why or how this changed, read through the next paragraph as well. Or even checkout my other posts about arch.

Why do we need to replace docker-compose?

Docker is currently in the process of merging docker-compose into the docker specification and uses the rolling release community as testing group. You might have noticed that your error message for docker-compose disable-v2 already told you that you should look into docker compose COMMAND --help for help. Notice the space instead of the minus between docker and compose? This is a proof, that in fact your calls to docker-compose translate into the freshly migrated compose feature of Docker CLI.

To go back to the original docker-compose, we need to remove that translation and re-install the latest stable v1 binary. The older version is still maintained, but will be deprecated later on.

At one point, we should not care anymore, as docker-compose dependents will have adjusted to the changes introduced with v2, and we will happily move on.

Related Posts

Find posts on similar topics:

Support me via buymeacoffee

If I helped you solve a problem or you just like my content, consider supporting me by buying me a coffee.

Buy me a coffee