Before posting in the issue tracker

[zanieb]

👋 Thanks for engaging with uv! As maintainers, we must split our time between solving existing issues (by adding features and fixing bugs) and responding to new issues. We care a lot about responding to issues promptly. Help us out by opening high quality issues, identifying related issues, and ensuring that your issue is not a duplicate.

When to open a new issue

Before opening a new issue, please search for a similar issue. GitHub's search is frequently unreliable, we struggle to find issues we know exist, so we understand if you have a hard time finding an existing issue. We've included some common issues below to help you find issues we see frequently.

If you find a similar issue, please confirm that your issue is the same. If you are not certain if your issue is the same, it is best to create a new issue instead. Including a link to possible existing issues can save us a lot of time. Some error messages can look similar, e.g., during build failure, but we often need more information to help diagnose your issue and and it's best to avoid side-tracking an existing discussion.

If your request or problem is the same as an existing issue, please upvote the original post with a 👍 instead of adding a comment like "+1" or "I'm encountering this too". If you do comment, please make sure you're adding new context to the conversation.

If you encountered the same problem or have the same question as someone else, consider creating a new issue with a suggestion to improve the experience. For example, uv could show a different error message that would help explain its behavior. In this way, we can collaborate to prevent confusion in the first place and make uv easier to use.

What kind of information to include

When reporting a problem or asking a question, be sure to include the following:

• The version of uv
• The operating system
• The command that you ran
• The output of the command with the --verbose flag

Including this information can save a lot of back and forth and we'll be able to solve your problem faster.

A few notes to keep in mind:

• You can get more logs by setting the RUST_LOG=uv=trace environment variable. These logs can be very verbose, we recommend putting them in a <details> bock or a gist.
• If you're not on the latest version of uv, make sure that your issue is present using the latest version.
• If the behavior worked on a previous version of uv and regressed in a new version, please share all the versions you have tested.

The best issues include a minimal reproduction of the problem. A minimal reproduction is a small example that demonstrates the problem. This can take a few forms:

• A repository on GitHub and a command to run
• A Docker image and command
• A list of commands to run, e.g., uv init example && cd example && uv add ...

If your project is open source, it can be helpful to link to your actual GitHub repository you are encountering the problem in. However, this is not a minimal example — isolating the issue in a simple case without extraneous details is better. Including both can help us narrow down the problem.

If you're reporting a difference from pip, please be sure to share both the uv pip and pip commands used and their output. Read the pip compatibility guide to ensure the difference is not intentional.

See issues with the great writeup label for examples.

Popular requests

Check if your request has already been made:

• Allow creating a python shim on python install astral-sh/uv#6265
• Add option to upgrade all packages in the environment, e.g., upgrade --all astral-sh/uv#1419
• Using uv run as a task runner astral-sh/uv#5903
• Use settings from the pip configuration file (pip.conf) astral-sh/uv#1404
• Add a command to activate the virtual environment, e.g., uv shell astral-sh/uv#1910
• Add a uv build backend astral-sh/uv#3957
• Add a command to read and update (i.e., bump) the project version, e.g., uv version astral-sh/uv#6298
• Add support for managing Conda environments and packages astral-sh/uv#1703
• Add an option to store virtual environments in a centralized location outside projects astral-sh/uv#1495
• (🎁) Add a command to "upgrade" dependency constraints in the pyproject.toml astral-sh/uv#6794
• Expand environment variables in user-provided index URLs astral-sh/uv#5734

See the most upvoted issues for more.

Common duplicates

Check if your problem has been previously discussed:

• Can't use tkinter with new venv set up with uv astral-sh/uv#7036
• Lock files don't mesh with dynamic package version info astral-sh/uv#7533
• Tracking issue: uv backtracks on the wrong package astral-sh/uv#8157
• Consider discarding < 4 upper-bound on Requires-Python astral-sh/uv#4022
• Packages that fail to install under PEP 517 with build isolation astral-sh/uv#2252

See previous duplicate issues for more.