1 <!-- doc/src/sgml/install-windows.sgml -->
3 <chapter id=
"install-windows">
4 <title>Installation from Source Code on
<productname>Windows
</productname></title>
7 <primary>installation
</primary>
8 <secondary>on Windows
</secondary>
12 It is recommended that most users download the binary distribution for
13 Windows, available as a graphical installer package
14 from the
<productname>PostgreSQL
</productname> website at
15 <ulink url=
"https://www.postgresql.org/download/"></ulink>. Building from source
16 is only intended for people developing
<productname>PostgreSQL
</productname>
21 There are several different ways of building PostgreSQL on
22 <productname>Windows
</productname>. The simplest way to build with
23 Microsoft tools is to install
<productname>Visual Studio
2022</productname>
24 and use the included compiler. It is also possible to build with the full
25 <productname>Microsoft Visual C++
2015 to
2022</productname>.
26 In some cases that requires the installation of the
27 <productname>Windows SDK
</productname> in addition to the compiler.
31 It is also possible to build PostgreSQL using the GNU compiler tools
32 provided by
<productname>MinGW
</productname>, or using
33 <productname>Cygwin
</productname> for older versions of
34 <productname>Windows
</productname>.
38 Building using
<productname>MinGW
</productname> or
39 <productname>Cygwin
</productname> uses the normal build system, see
40 <xref linkend=
"installation"/> and the specific notes in
41 <xref linkend=
"installation-notes-mingw"/> and
<xref linkend=
"installation-notes-cygwin"/>.
42 To produce native
64 bit binaries in these environments, use the tools from
43 <productname>MinGW-w64
</productname>. These tools can also be used to
44 cross-compile for
32 bit and
64 bit
<productname>Windows
</productname>
45 targets on other hosts, such as
<productname>Linux
</productname> and
46 <productname>macOS
</productname>.
47 <productname>Cygwin
</productname> is not recommended for running a
48 production server, and it should only be used for running on
49 older versions of
<productname>Windows
</productname> where
50 the native build does not work. The official
51 binaries are built using
<productname>Visual Studio
</productname>.
55 Native builds of
<application>psql
</application> don't support command
56 line editing. The
<productname>Cygwin
</productname> build does support
57 command line editing, so it should be used where psql is needed for
58 interactive use on
<productname>Windows
</productname>.
61 <sect1 id=
"install-windows-full">
62 <title>Building with
<productname>Visual C++
</productname> or the
63 <productname>Microsoft Windows SDK
</productname></title>
66 PostgreSQL can be built using the Visual C++ compiler suite from Microsoft.
67 These compilers can be either from
<productname>Visual Studio
</productname>,
68 <productname>Visual Studio Express
</productname> or some versions of the
69 <productname>Microsoft Windows SDK
</productname>. If you do not already have a
70 <productname>Visual Studio
</productname> environment set up, the easiest
71 ways are to use the compilers from
72 <productname>Visual Studio
2022</productname> or those in the
73 <productname>Windows SDK
10</productname>, which are both free downloads
78 Both
32-bit and
64-bit builds are possible with the Microsoft Compiler suite.
79 32-bit PostgreSQL builds are possible with
80 <productname>Visual Studio
2015</productname> to
81 <productname>Visual Studio
2022</productname>,
82 as well as standalone Windows SDK releases
10 and above.
83 64-bit PostgreSQL builds are supported with
84 <productname>Microsoft Windows SDK
</productname> version
10 and above or
85 <productname>Visual Studio
2015</productname> and above.
87 For 2015 requirements:
88 https://docs.microsoft.com/en-us/visualstudio/productinfo/vs2015-sysrequirements-vs
89 For 2017 requirements:
90 https://docs.microsoft.com/en-us/visualstudio/productinfo/vs2017-system-requirements-vs
91 For 2019 requirements:
92 https://docs.microsoft.com/en-us/visualstudio/releases/2019/system-requirements
93 For 2022 requirements:
94 https://docs.microsoft.com/en-us/visualstudio/releases/2022/system-requirements
99 The tools for building using
<productname>Visual C++
</productname> or
100 <productname>Platform SDK
</productname> are in the
101 <filename>src\tools\msvc
</filename> directory. When building, make sure
102 there are no tools from
<productname>MinGW
</productname> or
103 <productname>Cygwin
</productname> present in your system PATH. Also, make
104 sure you have all the required Visual C++ tools available in the PATH. In
105 <productname>Visual Studio
</productname>, start the
106 <application>Visual Studio Command Prompt
</application>.
107 If you wish to build a
64-bit version, you must use the
64-bit version of
108 the command, and vice versa.
109 Starting with
<productname>Visual Studio
2017</productname> this can be
110 done from the command line using
<command>VsDevCmd.bat
</command>, see
111 <command>-help
</command> for the available options and their default values.
112 <command>vsvars32.bat
</command> is available in
113 <productname>Visual Studio
2015</productname> and earlier versions for the
115 From the
<application>Visual Studio Command Prompt
</application>, you can
116 change the targeted CPU architecture, build type, and target OS by using the
117 <command>vcvarsall.bat
</command> command, e.g.,
118 <command>vcvarsall.bat x64
10.0.10240.0</command> to target Windows
10
119 with a
64-bit release build. See
<command>-help
</command> for the other
120 options of
<command>vcvarsall.bat
</command>. All commands should be run from
121 the
<filename>src\tools\msvc
</filename> directory.
125 Before you build, you can create the file
<filename>config.pl
</filename>
126 to reflect any configuration options you want to change, or the paths to
127 any third party libraries to use. The complete configuration is determined
128 by first reading and parsing the file
<filename>config_default.pl
</filename>,
129 and then apply any changes from
<filename>config.pl
</filename>. For example,
130 to specify the location of your
<productname>Python
</productname> installation,
131 put the following in
<filename>config.pl
</filename>:
133 $config-
>{python} = 'c:\python310';
135 You only need to specify those parameters that are different from what's in
136 <filename>config_default.pl
</filename>.
140 If you need to set any other environment variables, create a file called
141 <filename>buildenv.pl
</filename> and put the required commands there. For
142 example, to add the path for bison when it's not in the PATH, create a file
145 $ENV{PATH}=$ENV{PATH} . ';c:\some\where\bison\bin';
150 To pass additional command line arguments to the Visual Studio build
151 command (msbuild or vcbuild):
157 <sect2 id=
"install-windows-full-requirements">
158 <title>Requirements
</title>
160 The following additional products are required to build
161 <productname>PostgreSQL
</productname>. Use the
162 <filename>config.pl
</filename> file to specify which directories the libraries
167 <term><productname>Microsoft Windows SDK
</productname></term>
169 If your build environment doesn't ship with a supported version of the
170 <productname>Microsoft Windows SDK
</productname> it
171 is recommended that you upgrade to the latest version (currently
172 version
10), available for download from
173 <ulink url=
"https://www.microsoft.com/download"></ulink>.
176 You must always include the
177 <application>Windows Headers and Libraries
</application> part of the SDK.
178 If you install a
<productname>Windows SDK
</productname>
179 including the
<application>Visual C++ Compilers
</application>,
180 you don't need
<productname>Visual Studio
</productname> to build.
181 Note that as of Version
8.0a the Windows SDK no longer ships with a
182 complete command-line build environment.
187 <term><productname>ActiveState Perl
</productname></term>
189 ActiveState Perl is required to run the build generation scripts. MinGW
190 or Cygwin Perl will not work. It must also be present in the PATH.
191 Binaries can be downloaded from
192 <ulink url=
"https://www.activestate.com"></ulink>
193 (Note: version
5.14 or later is required,
194 the free Standard Distribution is sufficient).
201 The following additional products are not required to get started,
202 but are required to build the complete package. Use the
203 <filename>config.pl
</filename> file to specify which directories the libraries
208 <term><productname>ActiveState TCL
</productname></term>
210 Required for building
<application>PL/Tcl
</application> (Note: version
211 8.4 is required, the free Standard Distribution is sufficient).
216 <term><productname>Bison
</productname> and
217 <productname>Flex
</productname></term>
220 <productname>Bison
</productname> and
<productname>Flex
</productname> are
221 required to build from Git, but not required when building from a release
222 file. Only
<productname>Bison
</productname> versions
2.3 and later
223 will work.
<productname>Flex
</productname> must be version
2.5.35 or later.
227 Both
<productname>Bison
</productname> and
<productname>Flex
</productname>
228 are included in the
<productname>msys
</productname> tool suite, available
229 from
<ulink url=
"http://www.mingw.org/wiki/MSYS"></ulink> as part of the
230 <productname>MinGW
</productname> compiler suite.
234 You will need to add the directory containing
235 <filename>flex.exe
</filename> and
<filename>bison.exe
</filename> to the
236 PATH environment variable in
<filename>buildenv.pl
</filename> unless
237 they are already in PATH. In the case of MinGW, the directory is the
238 <filename>\msys\
1.0\bin
</filename> subdirectory of your MinGW
239 installation directory.
244 The Bison distribution from GnuWin32 appears to have a bug that
245 causes Bison to malfunction when installed in a directory with
246 spaces in the name, such as the default location on English
247 installations
<filename>C:\Program Files\GnuWin32
</filename>.
248 Consider installing into
<filename>C:\GnuWin32
</filename> or use the
249 NTFS short name path to GnuWin32 in your PATH environment setting
250 (e.g.,
<filename>C:\PROGRA~
1\GnuWin32
</filename>).
258 <term><productname>Diff
</productname></term>
260 Diff is required to run the regression tests, and can be downloaded
261 from
<ulink url=
"http://gnuwin32.sourceforge.net"></ulink>.
266 <term><productname>Gettext
</productname></term>
268 Gettext is required to build with NLS support, and can be downloaded
269 from
<ulink url=
"http://gnuwin32.sourceforge.net"></ulink>. Note that binaries,
270 dependencies and developer files are all needed.
275 <term><productname>MIT Kerberos
</productname></term>
277 Required for GSSAPI authentication support. MIT Kerberos can be
279 <ulink url=
"https://web.mit.edu/Kerberos/dist/index.html"></ulink>.
284 <term><productname>libxml2
</productname> and
285 <productname>libxslt
</productname></term>
287 Required for XML support. Binaries can be downloaded from
288 <ulink url=
"https://zlatkovic.com/pub/libxml"></ulink> or source from
289 <ulink url=
"http://xmlsoft.org"></ulink>. Note that libxml2 requires iconv,
290 which is available from the same download location.
295 <term><productname>LZ4
</productname></term>
297 Required for supporting
<productname>LZ4
</productname> compression.
298 Binaries and source can be downloaded from
299 <ulink url=
"https://github.com/lz4/lz4/releases"></ulink>.
304 <term><productname>Zstandard
</productname></term>
306 Required for supporting
<productname>Zstandard
</productname> compression.
307 Binaries and source can be downloaded from
308 <ulink url=
"https://github.com/facebook/zstd/releases"></ulink>.
313 <term><productname>OpenSSL
</productname></term>
315 Required for SSL support. Binaries can be downloaded from
316 <ulink url=
"https://slproweb.com/products/Win32OpenSSL.html"></ulink>
317 or source from
<ulink url=
"https://www.openssl.org"></ulink>.
322 <term><productname>ossp-uuid
</productname></term>
324 Required for UUID-OSSP support (contrib only). Source can be
326 <ulink url=
"http://www.ossp.org/pkg/lib/uuid/"></ulink>.
331 <term><productname>Python
</productname></term>
333 Required for building
<application>PL/Python
</application>. Binaries can
334 be downloaded from
<ulink url=
"https://www.python.org"></ulink>.
339 <term><productname>zlib
</productname></term>
341 Required for compression support in
<application>pg_dump
</application>
342 and
<application>pg_restore
</application>. Binaries can be downloaded
343 from
<ulink url=
"https://www.zlib.net"></ulink>.
351 <sect2 id=
"install-windows-full-64-bit">
352 <title>Special Considerations for
64-Bit Windows
</title>
355 PostgreSQL will only build for the x64 architecture on
64-bit Windows.
359 Mixing
32- and
64-bit versions in the same build tree is not supported.
360 The build system will automatically detect if it's running in a
32- or
361 64-bit environment, and build PostgreSQL accordingly. For this reason, it
362 is important to start the correct command prompt before building.
366 To use a server-side third party library such as
<productname>Python
</productname> or
367 <productname>OpenSSL
</productname>, this library
<emphasis>must
</emphasis> also be
368 64-bit. There is no support for loading a
32-bit library in a
64-bit
369 server. Several of the third party libraries that PostgreSQL supports may
370 only be available in
32-bit versions, in which case they cannot be used with
375 <sect2 id=
"install-windows-full-build">
376 <title>Building
</title>
379 To build all of PostgreSQL in release configuration (the default), run the
382 <userinput>build
</userinput>
384 To build all of PostgreSQL in debug configuration, run the command:
386 <userinput>build DEBUG
</userinput>
388 To build just a single project, for example psql, run the commands:
390 <userinput>build psql
</userinput>
391 <userinput>build DEBUG psql
</userinput>
393 To change the default build configuration to debug, put the following
394 in the
<filename>buildenv.pl
</filename> file:
396 $ENV{CONFIG}=
"Debug";
401 It is also possible to build from inside the Visual Studio GUI. In this
402 case, you need to run:
404 <userinput>perl mkvcbuild.pl
</userinput>
406 from the command prompt, and then open the generated
407 <filename>pgsql.sln
</filename> (in the root directory of the source tree)
412 <sect2 id=
"install-windows-full-clean-inst">
413 <title>Cleaning and Installing
</title>
416 Most of the time, the automatic dependency tracking in Visual Studio will
417 handle changed files. But if there have been large changes, you may need
418 to clean the installation. To do this, simply run the
419 <filename>clean.bat
</filename> command, which will automatically clean out
420 all generated files. You can also run it with the
421 <parameter>dist
</parameter> parameter, in which case it will behave like
422 <userinput>make distclean
</userinput> and remove the flex/bison output files
427 By default, all files are written into a subdirectory of the
428 <filename>debug
</filename> or
<filename>release
</filename> directories. To
429 install these files using the standard layout, and also generate the files
430 required to initialize and use the database, run the command:
432 <userinput>install c:\destination\directory
</userinput>
437 If you want to install only the client applications and
438 interface libraries, then you can use these commands:
440 <userinput>install c:\destination\directory client
</userinput>
445 <sect2 id=
"install-windows-full-reg-tests">
446 <title>Running the Regression Tests
</title>
449 To run the regression tests, make sure you have completed the build of all
450 required parts first. Also, make sure that the DLLs required to load all
451 parts of the system (such as the Perl and Python DLLs for the procedural
452 languages) are present in the system path. If they are not, set it through
453 the
<filename>buildenv.pl
</filename> file. To run the tests, run one of
454 the following commands from the
<filename>src\tools\msvc
</filename>
457 <userinput>vcregress check
</userinput>
458 <userinput>vcregress installcheck
</userinput>
459 <userinput>vcregress plcheck
</userinput>
460 <userinput>vcregress contribcheck
</userinput>
461 <userinput>vcregress modulescheck
</userinput>
462 <userinput>vcregress ecpgcheck
</userinput>
463 <userinput>vcregress isolationcheck
</userinput>
464 <userinput>vcregress bincheck
</userinput>
465 <userinput>vcregress recoverycheck
</userinput>
468 To change the schedule used (default is parallel), append it to the
471 <userinput>vcregress check serial
</userinput>
474 For more information about the regression tests, see
475 <xref linkend=
"regress"/>.
479 Running the regression tests on client programs, with
480 <command>vcregress bincheck
</command>, or on recovery tests, with
481 <command>vcregress recoverycheck
</command>, requires an additional Perl module
485 <term><productname>IPC::Run
</productname></term>
487 As of this writing,
<literal>IPC::Run
</literal> is not included in the
488 ActiveState Perl installation, nor in the ActiveState Perl Package
489 Manager (PPM) library. To install, download the
490 <filename>IPC-Run-
<version
>.tar.gz
</filename> source archive from
491 <acronym>CPAN
</acronym>,
492 at
<ulink url=
"https://metacpan.org/dist/IPC-Run"></ulink>, and
493 uncompress. Edit the
<filename>buildenv.pl
</filename> file, and add a PERL5LIB
494 variable to point to the
<filename>lib
</filename> subdirectory from the
495 extracted archive. For example:
497 $ENV{PERL5LIB}=$ENV{PERL5LIB} . ';c:\IPC-Run-
0.94\lib';
505 The TAP tests run with
<command>vcregress
</command> support the
506 environment variables
<varname>PROVE_TESTS
</varname>, that is expanded
507 automatically using the name patterns given, and
508 <varname>PROVE_FLAGS
</varname>. These can be set on a Windows terminal,
509 before running
<command>vcregress
</command>:
511 set PROVE_FLAGS=--timer --jobs
2
512 set PROVE_TESTS=t/
020*.pl t/
010*.pl
514 It is also possible to set up those parameters in
515 <filename>buildenv.pl
</filename>:
517 $ENV{PROVE_FLAGS}='--timer --jobs
2'
518 $ENV{PROVE_TESTS}='t/
020*.pl t/
010*.pl'
523 Additionally, the behavior of TAP tests can be controlled by a set of
524 environment variables, see
<xref linkend=
"regress-tap-vars" />.
528 Some of the TAP tests depend on a set of external commands that would
529 optionally trigger tests related to them. Each one of those variables
530 can be set or unset in
<filename>buildenv.pl
</filename>:
533 <term><varname>GZIP_PROGRAM
</varname></term>
535 Path to a
<application>gzip
</application> command. The default is
536 <literal>gzip
</literal>, which will search for a command by that
537 name in the configured
<envar>PATH
</envar>.
542 <term><varname>LZ4
</varname></term>
544 Path to a
<application>lz4
</application> command. The default is
545 <literal>lz4
</literal>, which will search for a command by that
546 name in the configured
<envar>PATH
</envar>.
551 <term><varname>OPENSSL
</varname></term>
553 Path to an
<application>openssl
</application> command. The default is
554 <literal>openssl
</literal>, which will search for a command by that
555 name in the configured
<envar>PATH
</envar>.
560 <term><varname>TAR
</varname></term>
562 Path to a
<application>tar
</application> command. The default is
563 <literal>tar
</literal>, which will search for a command by that
564 name in the configured
<envar>PATH
</envar>.
569 <term><varname>ZSTD
</varname></term>
571 Path to a
<application>zstd
</application> command. The default is
572 <literal>zstd
</literal>, which will search for a command by that
573 name in the configured
<envar>PATH
</envar>.