Distribute a Conda Package¶
As with Setuptools, we also need to provide both some description and build instruction for a Conda package. More specifically, three files are needed:
meta.yaml
build.sh
blt.bat
Put them in the project root (alongside with other metadata files such as
README.md
, pyproject.toml
).
Creating meta.yaml¶
This is used to describe the package.
package:
name: sampleproject-YOUR-USERNAME
version: "0.0.1"
about:
home: https://github.com/pypa/sampleproject
license: MIT
summary: A small example package
source:
fn: sampleproject-YOUR-USERNAME-0.0.1.tar.gz
url: https://test.pypi.org/packages/source/s/sampleproject-YOUR-USERNAME/sampleproject-YOUR-USERNAME-0.0.1.tar.gz
md5: "39180d64b5021c5399a2568fe2103cd2"
requirements:
build:
- pip >=19
- python >=3.6
run:
- python >=3.6
Note
Remember to replace YOUR-USERNAME
with your own name.
Warning
Make sure to quote the version
and md5
fields! Otherwise YAML may
interpret them as numbers. Also, the extension is yaml
, not yml
.
Here, we instruct Conda about basic project information (package
and
about
sections), where to download it (source
), and what other packages
are needed in order to build and run it.
Unlike PyPI, Conda does not allow uploading source code (only built files), so
you need to upload your code somewhere else, and use meta.yaml
to tell
Conda where it is.
Here, we are re-using our data on Test PyPI (or the real PyPI, if you
eventually release the package to the public). The package URL is predictable,
and based on your package name (the first /s/
part is the package name’s
first letter).
The MD5 value is used by Conda to make sure it downloads the correct file. It can be calculated using a local command.
On Windows:
fciv -md5 dist\sampleproject-YOUR-USERNAME-0.0.1.tar.gz
On macOS:
md5 dist/sampleproject-YOUR-USERNAME-0.0.1.tar.gz
On Linux:
md5sum dist/sampleproject-YOUR-USERNAME-0.0.1.tar.gz
Alternatively, you can also view this on your PyPI project page at
https://test.pypi.org/project/sampleproject-YOUR-USERNAME/#files. Click on the
View button beside the .tar.gz
file, and copy the hash digest field on
the MD5 row.
Creating build scripts¶
Conda packages use two files to build: build.sh
and bld.bat
. These two
are basically the same thing, but one for installing on Windows, and one for on
Linux and macOS. It is highly recommended you provide both if possible
(unless you really don’t want the package to be installed on a platform).
build.sh
:
"$PYTHON" -m pip install --no-deps .
bld.bat
:
"%PYTHON%" -m pip install --no-deps .
exit %errorlevel%
Building the package¶
In the project root (where meta.yaml
is), use conda build
to generate a
Conda package:
conda build .
This will generates a lot of text. When it finished, you should see something like the following near the end:
TEST START: ~/miniconda/conda-bld/linux-64/sampleproject-YOUR-USERNAME-0.0.1-py38_0.tar.bz2
Nothing to test for: ~/miniconda/conda-bld/linux-64/sampleproject-YOUR-USERNAME-0.0.1-py38_0.tar.bz2
# Automatic uploading is disabled
# If you want to upload package(s) to anaconda.org later, type:
anaconda upload ~/miniconda/conda-bld/linux-64/sampleproject-YOUR-USERNAME-0.0.1-py38_0.tar.bz2
This means that the package has been built successfully. The TEST START
and
anaconda upload
lines also shows the location of the package; in this case
it is:
~/miniconda/conda-bld/linux-64/sampleproject-YOUR-USERNAME-0.0.1-py38_0.tar.bz2
Save this path somewhere; it will be useful in the following (optional) sections.
Testing the Conda package¶
You can try installing the newly built package into your Conda environment:
conda install --use-local sampleproject-YOUR-USERNAME
The --use-local
flag instructs Conda to install the local conda-build
channel on your computer, rather than the default Anaconda or conda-forge.
If installed successfully, the package will be present in conda list
.
Optional: Building for a different Python version¶
The package built above was against Python 3.8 (the file name contains a
py38
part). Conda by default builds packages for the version of Python
installed in the root environment. To build packages for other versions of
Python, use the --python
flag followed by a version:
conda build --python 3.6 sampleproject-YOUR-USERNAME
Notice that the file printed at the end of the output would change to reflect
the requested version of Python. When you conda install
, it will look in
the package directory for the file that matches your current Python version.
Optional: Converting a package for use on all platforms¶
Similar to the Python version, Conda by default requires you to build the
package on each platform, to make sure the uploaded files are always correctly
built. We built against linux-64
(Linux, 64-bit) in the above example.
Sometimes, however, you are very sure the package works on all platforms.
Conda can convert the package for you in this case:
conda convert --platform all ~/miniconda/conda-bld/linux-64/sampleproject-YOUR-USERNAME-0.0.1-py38_0.tar.bz2
Replace the final path with your package location saved above.
Optional: Uploading to Anaconda.org¶
After converting your files for use on other platforms, you may choose to upload your files to Anaconda.org. You will need to register an account (sign up) on the website first.
Make sure you have the Anaconda Client installed:
conda install anaconda-client
And log in (sign in) into your registered Anaconda account:
anaconda login
After that, you can use the command to upload packages:
anaconda upload ~/miniconda/conda-bld/linux-64/sampleproject-YOUR-USERNAME-0.0.1-py38_0.tar.bz2
Replace the final path with your package location saved above. Packages built
against another Python, or converted by conda convert
can also be uploaded
in the same way, to make your package support multiple Python versions and
platforms.