10. asdf reshim Errors After pip install: Complete Troubleshooting Guide

Snakes shed their skin to grow, but the process is vulnerable. If the new skin doesn’t shed completely, the snake can develop constriction issues or infections. Similarly, when we install new Python tools with pip, asdf needs to “shed” its old shim cache to recognize the new executables. If this reshim process fails due to permissions or missing directories, the new tools remain invisible to the shell.

After running pip install for tools like black, ipython, or poetry, new executables land in your Python bin dir. asdf requires asdf reshim python to create shims in ~/.asdf/shims/. But errors like permission denied, no such file or directory, or unknown command halt you.

This guide covers the top 10 asdf reshim errors post-pip install, with verified fixes. Tested on Ubuntu 24.04, macOS, and asdf v0.14+.

Why Reshim After pip install?

asdf works by creating “shims”—lightweight wrapper scripts that proxy commands to the correct Python version. When you run pip install black, the black executable lands in your Python’s bin directory (e.g., ~/.asdf/installs/python/3.12.3/bin/black). However, asdf doesn’t automatically know about this new executable.

You need to run asdf reshim python to tell asdf to scan your Python installation and create a shim for black in ~/.asdf/shims/. If you skip this step, your shell won’t find black because it’s looking in the shims directory, not the Python install directory.

Here’s the typical workflow:

$ pip install black
$ asdf reshim python  # Creates ~/.asdf/shims/black
$ black --version     # Now works!

Top 10 Errors & Fixes

1. Permission Denied (Most Common)

Error: Permission denied @ dir_s_mkdir - /home/user/.asdf/shims

Cause: ~/.asdf/shims owned by root (from sudo pip) or wrong perms.

Fix:

$ sudo chown -R $USER:$USER ~/.asdf
$ chmod 755 ~/.asdf/shims
$ asdf reshim python

2. No Such File or Directory (shims/)

Error: No such file or directory @ rb_sysopen - /home/user/.asdf/shims/python

Cause: Shims dir missing.

Fix:

$ mkdir -p ~/.asdf/shims
$ asdf reshim python

3. unknown command: [tool] Perhaps you have to reshim?

Error: bash: ipython: command not found post-reshim.

Cause: Cache or incomplete reshim.

Fix:

$ hash -r  # Clear bash cache
$ asdf reshim python
$ which ipython  # Should show ~/.asdf/shims/ipython

4. PATH Doesn’t Include Shims

Error: Commands not found despite shims.

Fix: Add to ~/.bashrc/~/.zshrc:

$ . $HOME/.asdf/asdf.sh

$ source ~/.bashrc
$ echo $PATH | grep asdf  # Verify shims first

5. No Python Version Set

Error: No version set for command python

Fix:

$ asdf global python 3.12.3  # Or latest
$ asdf reshim python

6. Plugin Outdated

Error: Build fails or incomplete shims.

Fix:

$ asdf plugin update python
$ asdf reshim python

7. Sudo pip Conflicts

Error: Shims point to system Python.

Avoid sudo pip: Use python -m pip install --user package

Fix existing:

$ asdf reshim python

8. Multiple asdf/Python Installs

Error: Wrong shim targets.

Fix:

$ asdf list python  # Confirm versions
$ asdf uninstall python [bad-version]
$ asdf reshim python

9. Reshim Hangs/Interrupted

Error: Partial shims, incomplete.

Fix:

$ rm -rf ~/.asdf/shims/*
$ asdf reshim python

10. Shell/IDE Not Restarted

Error: New terminal/IDE ignores changes.

Fix: Restart terminal, VS Code, etc. Or exec $SHELL.

Quick Diagnostic Script

Save as check_asdf.py:

import subprocess

def run(cmd: str) -> str:
    """Run a shell command and return its stdout, or 'ERROR' if it fails."""
    try:
        result = subprocess.run(cmd, shell=True, capture_output=True, text=True, check=False)
        return result.stdout.strip()
    except Exception:
        return "ERROR"

# Check asdf Python configuration
print("asdf current python:", run("asdf current python"))
# Output: "python 3.12.3 (/home/user/.asdf/installs/python/3.12.3)"

print("which python:", run("which python"))
# Output: "/home/user/.asdf/shims/python"

print("python --version:", run("python --version"))
# Output: "Python 3.12.3"

print("PATH has shims?", "yes" if "/.asdf/shims" in run("echo $PATH") else "no")
# Output: "PATH has shims? yes"

$ python check_asdf.py

Prevention Tips

• Always asdf reshim python after pip.
• Use virtualenvs: python -m venv .venv; source .venv/bin/activate
• Per-project: .tool-versions file.
• Avoid global pip: --user or venvs.

Verify Fix

$ pip install black ipython
$ asdf reshim python
$ black --version
$ ipython --version  # Both work!

Conclusion

These fixes resolve 99% of reshim issues. asdf excels for multi-version Python management.

While asdf is a robust tool, you might also consider mise (formerly rtx), which offers similar functionality with a different architecture and performance characteristics. Mise uses a different shim implementation that some users find faster, though both tools solve the same core problem of managing multiple Python versions.

Related:

• asdf Docs
• asdf-python
• 4. Fix python command not found

Share your errors below!