Before posting in the issue tracker

[zanieb]

👋 Thanks for engaging with uv! As maintainers, we must split our time between solving existing issues (e.g., 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 common issues. It's also important to search the documentation; we often see issues that are answered there.

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 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. Similarly, please do not request status updates on issues — if progress has been made, the issue is usually updated.

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 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.

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.

A few things to keep in mind:

• If you're not on the latest version of uv, make sure that your issue is still present on 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. This can help track down the cause of the bug. Regressions are generally given higher priority.
• Please avoid screenshots, and use markdown formatted text. Instead, copy the output text from your terminal. This improves discoverability via search and makes it easier for maintainers to interact with the output.
• 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> block or a gist.
• 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 #6265
• Add option to upgrade all packages in the environment, e.g., upgrade --all #1419
• Using uv run as a task runner #5903
• Use settings from the pip configuration file (pip.conf) #1404
• Add a command to activate the virtual environment, e.g., uv shell #1910
• Add a uv build backend #3957
• Add a command to read and update (i.e., bump) the project version, e.g., uv version #6298
• Add support for managing Conda environments and packages #1703
• Add an option to store virtual environments in a centralized location outside projects #1495
• (🎁) Add a command to "upgrade" dependency constraints in the pyproject.toml #6794
• Expand environment variables in user-provided index URLs #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 #7036
• Lock files don't mesh with dynamic package version info #7533
• Tracking issue: uv backtracks on the wrong package #8157
• Consider discarding < 4 upper-bound on Requires-Python #4022
• Packages that fail to install under PEP 517 with build isolation #2252

See previous duplicate issues for more.

---

Want to provide feedback on this document? See #9453