# Implementing a `conda doctor` command

In this article I discuss the much requested `conda doctor` command, what is expected of it, what is feasible at the moment, and how we could implement it.

## What is expected of `conda doctor`?
The `conda doctor` command was first suggested/requested around 9 years ago. See [this](https://github.com/conda/conda/issues/474) GitHub issue.
It was first suggested that `conda doctor` display detailed information about environment variables, compilers, OS information etc. But such information was already covered by `conda info --all`.
Hence after further discussions and feedback the expectation from `conda doctor` were boiled down to "**diagnose environment integrity/health**".

## A list of requested information about environment health:

1. SAT satisfiability of an environment
2. Are the packages satisifed (according to the solver). IIRC, this happens anytime there are package changes in an environment.
3. Are all the files present in the environment? This would verify that all files that are claimed to be in the environment, are actually present. Mapping os.path.exists on the files list in the conda-meta json files accomplishes this. Are files that are supposed to be hardlinked/symlinked actually hardlinks/symlinks?
4. sha256 and size of every path in the environment (or alternately if path is missing)
5. the existence of non-tracked files in an environment
6. Is the environment listed on environments.txt ?
7. Check file permissions.
8. overlapping paths in conda-meta for an environment
9. if pip has replaced entire packages and conda-meta is out-of-date

## Detailed analysis of the requests above:

### 1. SAT satisfiability of an environment :negative_squared_cross_mark:
In [this](https://anaconda.slack.com/archives/C030CB9UQQN/p1667924619775219) slack discussion it is agreed that we would for now want to ignore this request.

### 2. Are the packages satisifed (according to the solver). :heavy_check_mark:
This happens anytime there are package changes in an environment.
"Satisfied" refers to the solver saying that the matchspec has been resolved and all resulting dependencies and versions are already installed in the current environment.

### 3. Are all the files present in the environment? :heavy_check_mark: (implemented)
This would verify that all files that are claimed to be in the environment, are actually present. Mapping os.path.exists on the files list in the conda-meta json files accomplishes this. Are files that are supposed to be hardlinked/symlinked actually hardlinks/symlinks?

#### Summarize
We check whether all the claimed files (packages) in the environment are actually present in it or not. We then check whether all these packages are satisfied or not.

### 4. sha256 and size of every path in the environment (or alternately if path is missing) :heavy_check_mark: (partially implemented)
The purpose of this is to know if any package has been altered (indicated by changed sha256 key).
Instead of displaying the sha256 of all packages, we could display the list of altered packages.

### 5. the existence of untracked files in an environment :heavy_check_mark:
Untracked files are those that exist in the environment but weren't installed by conda.“Untracked” basically means “not managed by conda”, so if, e.g., you `conda export` the environment, that file won’t be included. (edited)

### 6. Is the environment listed on environments.txt ? (implemented) :woman-shrugging:
Every new environment gets listed on the `environments.txt` file in the .conda directory. But if the files gets deleted, the contents cannot be retrieved.

### 7. Check file permission
File permissions would mean ensuring that one can read and write everything contained within a conda environment.
Perhaps the `conda doctor --info` could be the one

**I do not understand point #8.**

### 9. If pip has replaced entire packages and conda-meta is out-of-date
This would be the case if I for example installed a package originally with conda but then later installed the same thing with pip.

Usually, pip would just ignore this, but if you downgrade a package, this could totally happen. For example, if I create an environment with the package "requests" and then used pip to install an older version of "requests", the information in the "conda-meta" folder would be incorrect because it would only be aware of the version that conda installed.

`conda doctor` could display the list of packages with version

## Based on above analysis, a list of stats `conda doctor` could display

1. Missing Packages (#3)
2. Unsatisfied Packages (#2)
3. Altered packages (#4)
4. Untracked files (#5)

### Prototype

running `conda doctor` could display the following:


### More detailed statistics about the environement health could be displayed using `conda doctor -v`

More detailed stats could include:
* Names of the missing packages,
* name of the unsatisfied packages and their missing dependencies, sha256 keys of the altered packages,
* names of the untracked files.
* From point #7, `conda doctor -v` could also display the permission various files have.
* From point #9, `conda doctor -v` could display the list of packages with installed versions different from those mentioned in the conda-meta.

---

## Can this command be a plugin? Why or why not?
Based on my discussion with Bianca we were able to conclude that `conda doctor` can indeed be implemented as a plugin.
It will help show how conda can use plugins internally as well, and not only for some user built functionality.

## Why will this command be useful?
One place for users to see all inconsistencies in their environment.
Output of this command will help them others debug their environment.

This could especially be helpful for us, the conda developers, but also for internal IT support staff that may be wishing to fix issues themselves.

In our issue template we request users to share with us the result of `conda info`, `conda config` , maybe after implementing `conda doctor`, we could ask them to share the result of `conda doctor`.